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Abstract 


This report introduces a technique of software documentation 
called conjunctive programming and discusses its role in the devel- 
opment and maintenance of software systems. The report also de- 
scribes the Coq/oin tool, an adjunct to assist practitioners. Aimed at 
supporting software reuse while conforming with conventional devel- 
opment practices, conjunctive programming is defined as the extrac- 
tion, integration, and embellishment of pertinent information ob- 
tained directly from an existing database of software artifacts, such 
as specifications, source code, configuration data, link-edit scripts, 
utility files, and other relevant information, into a product that 
achieves desired levels of detail, content, and production quality. 
Conjunctive programs typically include automatically generated ta- 
bles of contents, indexes, cross references, bibliographic citations, ta- 
bles, and figures (including graphics and illustrations). This report 
presents an example of conjunctive programming by documenting 
the use and implementation of the Coq/oin program. 
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1 INTRODUCTION 

1.1 Documentation Problems 

One of the traditional problems with maintaining and reusing computer pro- 
grams is understanding — even by the authors, after a period of time has elapsed. 
Another is consistency among the software artifacts (program and library code, 
documents, linkage-edit files, databases, etc.) as time progresses and as adap- 
tations evolve within multiple platforms. 

Each programmer has a particular individual manner of writing programs 
that includes organization and composition, choice of algorithms, method of 
indentation, density of comments, naming of variables, extent of information 
hiding, application of modular packaging, and form of expression. In addition, 
the visual appearance, including typography and graphics, may vary according 
to the programmer’s personal style. It remains a fact that a program written 
by someone else may be very difficult to understand, even when produced by 
acceptable development practices. 

Some advocate “self-documenting code ” or intensely annotated programs 
that contain all the information that the programmers believe is necessary. 
Making a program entirely readable by itself is, in some sense, analogous to 
making a circuit board or computer chip layout readable by itself: It is a dif- 
ficult process usually producing unsatisfactory results that are not appropriate 
for the medium. Rather, readability gains where explanation, clarity, struc- 
ture, visualization, layout, use of color, and rendering can be separately and 
adequately treated. 

In the past, software artifacts were viewed by humans as documents. In the 
automated world of today, however, the concept of what a document is has un- 
dergone a vast change. The computer and communications industries have made 
enormous progress in giving humans immediate access to huge stores of informa- 
tion. The majority of this information, captured in printed material, libraries, 
and computer files, is ultimately for human perception. Some information is 
fully formatted for immediate and direct perception as printed matter. Some 
is fully formatted, ready to be rendered into perceivable form (e.g., PostScript 
files, digital video, and sound recordings). The rest is stored unformatted, but 
in such a way that it is possible to format, process, or otherwise render it for 
direct perception (e.g., in databases and in multimedia hypertext documents). 
In the future, expansion of the documentation concept to include an even wider 
context of perception will, no doubt lead to new needs for people to locate, per- 
ceive, and interactively understand not only software artifacts, but large bases 
of information of arbitrary types as well. 

Software documentation problems have sprung from a number of diverse 
sources, among which are the lack of accepted, effective industry-wide stan- 
dards; the conspicuous absence of software documentation courses in university 
curricula; the inadequate training within corporate development programs; the 
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emphasis within existing standards on form, rather than on substance and suf- 
ficiency; the uncertainty in, ignorance of, and insensitivity of developers to 
the needs of readers; the inability to provide the proper level and content of 
material needed by users; the prohibitively high cost of providing highly read- 
able, textbook-quality documentation; the pressure by managers and customers 
to “get the code working”; the deficient allocations of resources for providing 
proper documentation; the shortfall of practical methods and friendly, inte- 
grated tools for doing a good documentation job; and the lack of cost-effective 
means for combating the continuing entropic divergence in consistency among 
artifacts. 

In a recent visit to the library of the JPL Software Resource Center, an 
organization formed to guide the improvement of the Laboratory’s software en- 
gineering methods and practices, I found only one text completely devoted to 
documenting a program [1], and one other on diagrammatic methods applied 
to programming [3]. The I^TgX [4] reference manual was there, but that text 

tells how to compile a document, not how to document a program. Some of the j 

library’s texts devoted space to defining the documentation problem, justifying ! 

why projects should improve their documentation and giving examples of doc- L 

ument outlines, code annotation, review guidelines, and subjective acceptance I 

criteria. However, not one of the texts offered a real, codified, practical and | 

comprehensive approach to program understanding. Such works may exist, but 
at JPL their teachings are not part of the culture. 

Most of us in the software industry have taken high school and university 
courses in composition. We have at least been exposed to the art of literary 
discourse, expression, style, and organization. If we have forgotten, or otherwise 
need to (re)learn how to communicate in writing, there are books, reference 
works, and computerized tools readily available to help us at all levels of ability. 

It would therefore seem more natural for us to be able to explain something in 

our natural language than in a syntactically more restricted, awkward computer l 

language form. But a formula for producing software understandability is a tall ^ 

order. When applied by the practitioner, it must be capable of causing objects f 

to be created that will communicate the intended information to the intended : 

readers of presupposed intelligence levels, areas of skill, and cognitive styles [2]. 

This formula may not exist. 

In my experience, the best software documentation exists in journal articles 
and in textbooks on algorithms. In each of these understandability has been 
scrutinized by referees and editors. Unreadable works are rejected before their 

release to the public, and works of inferior quality that leak through the review “ 

process are generally short-lived. Those that survive serve as examples of the 

high quality that can be attained. ' 

In one not atypical work [5], I noted that the ratio of space devoted to ■ 

accompanying narrative, mathematical formulae, derivation, figures, tables, and | 

other explanatory material exceeded the space devoted to displaying the code 
by a factor ranging from about two to ten! If this one sample is anywhere near 
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to being a valid indicator, and if textbook quality is what is really required for 
reader understanding, then industry must expect its software projects to require 
a far greater proportion of time and resources on documentation than any other 
development pursuit. Indeed, most projects of any size will not be able to afford 
textbook-quality documentation. 

Sadly, I do not have a general approach to solving the overall documenta- 
tion problem either. Far more resources than I have, and wiser faculties than 
mine have attacked the problem vigorously for many years, with only meager 
success. This report does, however, offer a concept, a practical approach, and 
a simple tool to demonstrate a practice that, I hope, will help to increase pro- 
grammer sensitivity to the needs of readers, assist in producing good documents 
in normal documentation time , permit separate development and documenta- 
tion efforts to take place, and promote consistency among software artifacts. I 
believe that any level of content a project may decide upon for a document, from 
copious detail in meticulous, multi-linked, multicolored hypermedia, to no doc- 
umentation at all, can be accommodated within this concept. Whatever form 
of documentation is chosen, from textbook or journal rigor, to Department of 
Defense standards, to undisciplined personal quirks, can be created. As long as 
the sources of software artifacts are accessible within the system environment, 
the documentation process should be able to apply the technique presented in 
this report. 

1.2 Document Markup 

One concept central to the approach of this report is that ancillary information 
may be benignly inserted into software artifacts so as either to enhance the 
primary information content or extend the utility of those artifacts. Markup is 
a type of information that is introduced into data to convey special interpre- 
tations. It is so called because of its resemblance to the markings that editors 
make in drafts of paper documentation. Markup makes use of “start tags” and 
“end tags” that respectively precede and follow each logical portion of the data. 
Tags are specially formed so that the markup can be recognized and processed 
separately from data that surround it. 

Markup tags fall into four categories: 

(1) Descriptive markup, which defines the structure and appearance of a doc- 
ument. These tags identify such items as sections, subsections, citations, 
references, fonts, and so on. 

(2) Entity references, which are requests for objects to be moved into the 
document at (or near) the point of reference. The objects themselves may 
reside elsewhere within the medium containing the reference, or externally. 

(3) Markup declarations, which are statements that control how the markup 
is interpreted. These can be used to define objects directly and also to 
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create additional markup descriptions. 

(4) Processing instructions, which are instructions to the processing system, 
in its own language, to take specific actions. Unlike the three other types 
of markup, this markup is system-dependent, and perhaps application- 
dependent, as well. 

Markup tags do not need to be physically embedded within the information 
medium itself. They can be maintained in a separate database that defines the 
type, location, and other particulars of each mark. 

American industry and the international community have developed the 
Standard Generalized Markup Language (SGML) [6], and are in the draft stage 
of developing HyTime, a Hypermedia/Time-based document-structuring lan- 
guage [7] built on SGML. These standards offer ways to make “information 
about information” interoperable. An introductory article on HyTime appears 

in [8]. — - 

In a markup system, when a document type (such as a book, an article, or 
a report) is defined, a distinction is made between the information to be pre- 
sented and the instructions for rendering that information lor perception. This 
is a fairly straightforward process for many traditional types of documents, 
where information consists of printable words, punctuation, and simple graph- 
ics. Formatting a document follows a style guide, or specification that associates 
rendering instructions with generic markup tags. All that is necessary to refor- 
mat an entire document is to apply a different style guide. 

Markup tagging offers another, even more significant, benefit: collections 
of tagged objects may be queried like databases. By using special tags for 
interlinking objects, information products can access the contents of other in- 
formation products by reference. The use of automated query data involving 
actual objects, rather than manually generated surrogates of those data, can 
help immunize the produced documents against obsolescence. Moreover, the in- 
formation in tagged objects remains available for other uses totally unforeseen 
when the objects and tags were created. 

Markup tagging for document rendering and style must be recognized by the 
target document-processing system. Tagging for location of information must be 
recognized by the agents that establish and utilize linkages among objects. The 
placement and maintenance of linkage tags are the responsibilities of authors 
and owners of the information objects queried. 

1.3 Literate Programming 

Donald E. Knuth of Stanford University released a markup style utility in 1983 
named WEB [11] as part of a project that also developed the markup system 
and document compiler [12]. The use of WEB by Knuth [13] and others [14, 15, 16, 
17], led to the literate programming paradigm, a concept in which programs are 
treated as works of literature. The idea behind this approach to programming 
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is that software (code, documentation, and associated data) can be made so 
readable and interesting that it may actually be read for entertainment. If an 
author has craft and style, and if a program does something interesting, or does 
something in an interesting way, then the presentation to the reader can be 
enjoyable, as well as enlightening. 

Literate programs have an orientation and expression that differs from other 
programs. The literate program is a special mixture of expository text that tells 
the reader what the program does, how it does it, and why it does it that way. 
Not by accident, it also tells the compiler how to build the program. Thus, 
the program’s documentation, code, and data are integrated and in one place, 
possibly in a single computer file. They are created and maintained together as 
a unit. 

Unlike any other procedural programming language, WEB programmers are 
not required to present the pieces of a program in any specific order. Rather, 
they can be arranged in a natural order, which Knuth refers to as stream of 
consciousness f and they can be organized into segments that accommodate the 
needs of structured programming. Rather than developing “self-documenting 
code,” literate programmers create “self-coding documents.” 

WEB comprises two program utilities, WEAVE and TANGLE, which process the 
literate source files and create, respectively, a document file to be processed by 
T^}X and a code file to be processed by a Pascal (or other) compiler. The details 
of WEB and literate programming are described in Wayne Sewell’s well-written 
book, Weaving a Program: Literate Programming in WEB [18]. 
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2 CONJUNCTIVE PROGRAMMING 

This section describes an alternate to literate programming, a concept that I 
call conjunctive programming. 1 Because it is simple, easy to learn, flexible, and 
compatible with almost any documentation regimen, many may find it tote an 
appealing and useful adjunct to literate programming. 

The idea is not new. Like modularity and object-oriented methodology, 
many may realize they have been doing something like it for years without 
knowing that was what it was. While this report primarily treats generation 
of conventional text-and-graphics types of documents, extensions to multimedia 
and hypertext forms will be readily recognized. A hypermedia example of a 
similar concept, called Intermedia appears in [10]. 


2,1 The Concept 

In conjunctive programming, an object is any form of electronically accessible 
information. A software system is comprised of the set of objects that define, 
build, configure, and operate the system. These objects, therefore, contain 
much (but rarely all) of the information needed to understand the system. This 
information is current and accurate, because it is the real McCoy, not an artificial 
surrogate maintained separately. It is a resource that can be used and reused 
by excerpting appropriate portions into desired external documented forms. 

The verb conjoin means [19] to unify and integrate separate entities together 
for a common purpose. The adjective form conjunctive means connected, 
conjoined, and composed of, or functioning as, a combination. Conjunctive 
programming, then, is the assembling together of information excerpted from 
real software artifacts, such as programs, items in accessible libraries, version- 
specific configuration data, link-edit code, scripts, other documents, outputs 
from other processors (e.g., structure analyzers, pseudocode systems, statistical 
packages, etc.), and all other information required to create a document with 
designated levels of detail, content, and production quality. 

Producing a conjunctive program is somewhat similar to the “cut-and-paste” 
process one exercises when writing a document using a text editor or word 
processor on various sources of online data. It differs in that after an excerpt to 
be reused has been located, it is not pasted directly into the document at that 
time. Rather, a window to this excerpt is pasted into the conjunctive document 
instead. The window is alive; if the excerpt changes, the view of it in the window 
changes also. When the time to produce the target document finally arrives, 
a software tool scans the source document, taking snapshots through all the 
windows, replicating their current views. 

The product of this process may be likened to a collage, in that it is an artis- 
tic composition made of various diverse fragments of heterogeneous materials 

i Warning: Conjunctive literitia is a mental condition thought to be linked to the overzeal- 
ous devotion to this practice. 
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assembled (glued) together. However, this analogy cannot be further extended 
to describe the conjunctive programming process, for there is no listed adjective 
form describing the collage-making activity. Coined terms such as collage- 
nous ” “collagenative ” and “collageneric ” seem awkward, contrived, and inad- 
equate. It is true that “collage” can be used as a transitive verb, but it sounds 
awkward to describe conjunctive programming as a process of “coilaging” bits 
and pieces of existing information together. 

Conjunctive programming is a generic concept, specific instances of which 
are defined by the environment of automated utilities that provide for acquiring, 
editing, interrelating, integrating, navigating, and finally rendering the informa- 
tion products. In concept, conjunctive programming does not require markup 
tagging for these functions, but as a practical matter, it offers a great conve- 
nience. Intermedia is an example of a highly integrated conjunctive program- 
ming Environment in which the actual linkage mechanisms are largely hidden 
from user view. The degree to which conjunctive mechanisms are invisible within 
a programming environment that capitalizes on the benefits they provide attests 
the level of sophistication and utility of the environment. 

But the use of conjunctive programming does not have to be restricted only 
to highly integrated, grandiose environments. Rather, as illustrated in this 
report, it can be applied productively evenb less sophisticated, relatively het- 
erogeneous environments. Processors like TfcX and its dialects provide a sig- 
nificant portion of the mechanical advantage needed, permitting people with 
ordinary text editors to produce high-quality, typeset documents. IaTjtX and 
are powerful style adjuncts of T£X that help create and render ti- 
tles, abstracts, tables of contents, numbered sections, footnotes, tables, figures, 
indexes, cross-references, bibliographies, and citations. With I £X and OTgX 
serving as its basis, an effective conjunctive programming environment addi- 
tionally only requires a simple capability for recognizing and transcribing entity 
references among software artifacts. Existing development tools, such as file 
analyzers, type font managers, special formatters, program tree plotters, cross- 
reference generators, spelling checkers, thesauruses, and MAKE 2 programs with 
dependency files, can also augment the environment. 

Conjunctive programming in TgX can produce the same superior document 
quality as produced by literate programming in WEB. A I^X-based conjunctive 
programming environment and information flow are illustrated in Figure 1. 

The conjunctive programming approach to software development is differ- 
ently oriented than that of literate programming, even though one hopes that 
conjunctive programs can be equally literary in their final products. Conjunc- 
tive programs, like literate programs, are displayed as interspersed narrative, 
code, and data, printed in typeset quality. Actual source code, configuration 
data, link and library directives, MAKE files, and the like, are all sewn together 

2 MAKE is a utility (from UNIX) for automated regeneration of artifacts that are dependent 
on other artifacts, which may change from time to time. 
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Figure 1: TgX-based Conjunctive Programming Information Flow. 


into a format not unlike that of literate programs. The difference is that con- 
junctive programming presumes that the code, data, documentation, and other 
artifacts are maintained in separate, conventional forms that are then merged 
into the integrated final form seen by the reader. 

The practice of conjunctive programming may be pursued at different levels: 
art, craft, discipline, or mere application. The art of conjunctive programming 
exhibits conspicuous ingenuity and creative imagination, as may be manifested 
by an engaging manner of description, innovative articulation, clever insights 
and revelations, and curious mysteries for the reader to ponder and solve. Craft 
is evidenced by technical accuracy, rigor, and expert workmanship. Conjunctive 
programming discipline is the observance of orderly, sound, and systematic pro- 
cesses which conform to recognized sets of rules, standards, or guidelines. The 
mere practice of conjunctive programming does not, in itself, attest the level of 
talent and skill that is at work. 

Conjunctive programs contain linkages into real-world objects that may be 
subject to a form of entropic degradation caused by evolutionary changes in the 
system. As a practical matter, it is impossible either to prevent or counter this 
degradation in a timely fashion without the cooperation of the individuals re- 
sponsible for each linked- to object, or without elaborate automated linkage man- 
agement, or both. Both require the use of markup standards, automatic recog- 
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nition of changes, and establishment of communications and coordinated actions 
among the individuals and artifacts involved. The integrated Intermedia sys- 
tem for maintenance of linkage information in hypermedia documentation is 
discussed in [10]. 

Documents may suffer from incompleteness, inconsistency, noncurrency, and 
asynchrony, if improperly written or maintained. Whether a program descrip- 
tion is complete is perhaps more subjective in conjunctive programs than in 
literate programs, because only the code segments deemed of interest may have 
been abstracted into a conjunctive document, whereas the entire program must 
appear in the literate program. On the other hand, conjunctive programs can 
also be complete; they can also produce additional reports and papers about 
selected algorithms, data structures, and the more essential aspects of the pro- 
gram. Thus, conjunctive programming can either be equally elaborate as, or 
considerably simpler than, conventional literate programming, at the whim (and 

according to the resources) of the author. 

Conjunctive programming allows freedom of expression for whatever good it 
may inspire. It also serves those who must more rigorously conform to industry 
or government standards. Certainly the tools of conjunctive programming are 
capable of capturing and expressing far more literate examples of programming 
than will be seen here. The fault lies not in the conjunctive programming 
concept, nor with the use of the tools, but rather, as in all programming, in the 
capability of the pra ctit ioner and the time resources available. 

Consistency is the degree to which artifacts are internally and externally free 
from contradictions. Consistency conveys compatibility in content, style, and 
terminology. One form of consistency relates to currency, which is the degree 
to which the documentation correctly applies to the existing system. Literate 
programs are guaranteed to be current in coding specifications by their construc- 
tion. Parts of a literate program may be incorrect or in conflict, but these parts 
always define the program totally, for better or for worse. Conjunctive programs 
draw system information directly from the system database. Whether copied 
completely or correctly, the objects conjoined are true reflections^! what is in 
the system. Automated updates of documentation using MAKE whenever system 
changes are made will help to keep conjunctive programs current. The Con/oin 
tool currently does not search for inconsistencies but will complain whenever 
directives are inconsistent with the content of the artifact being accessed. 

Synchrony is the degree of consistency between referenced portions of sys- 
tem files and the contexts of the documents in which these excerpts appear. 
If maintenance deletes a code segment previously excerpted into a document, 
asynchrony appears as a “hole,” or error, in the document context. If a pro- 
gram modification erroneously moves an entity reference key, the code viewed 
may not pertain to the document subject matter at that point. Synchronism of 
document text and excerpted material requires robustness in the entity refer- 
ence scheme and immunity to changes in the system. More about the creation 
of robust entity reference keys appears later in this report, in Section 5.2. 
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2.2 Life Cycle Considerations 

Conjunctive programming methodology need not be limited to the code devel- 
opment and maintenance portions of the software life cycle. There is nothing 
inherent in the conjunctive programming concept that restricts linkages only to 
established portions of program code. Conjunctive programming can serve all 
phases of the life cycle, because these involve separate, but highly interrelated, 
products. Life cycle documents include project plans, work implementation 
plans, statements of work, quality assurance plans, configuration management 
plans, and various technical documents governing and resulting from the soft- 
ware implementation. Each of these products may contain information that is 
identical to, or closely related to, information in other products. Productiv- 
ity and document currency are potentially improved by conjunctive methods 
applied to the project artifacts. 

For example, planning documents often refer to budget goals, obligations, 
and actual costs; to schedule commitments, milestones, and accomplishments; 
and to resource constraints, workforce loading, and facility utilization profiles 
that are planned, monitored, and controlled. These resources are likely to be 
tracked by a project management system and controlled by the corporate ac- 
counting system. Conjunctively programmed project-planning documents can 
access the actual controlling repositories for accurate and current information, 
perhaps via interfacing tools. 

Requirements documents commonly cite and/or repeat material from gov- 
erning and auxiliary documents, system documents, user manuals, interface 
agreements, and results of analyses. Design documents cite material from the 
governing system and interface requirements, user manuals, outputs of design 
tools, program design analyzers, etc. All are ripe candidates for the conjunctive 
approach. 

Maintenance documents require detailed as-built design specifications, in- 
cluding construction information in the form of code structure, MAKE files, linkage 
edit instructions, batch scripts, software interface specifications, etc. Section 7 
and the appendices give examples of the use of conjunctive programming to 
record system implementation information. 

Planning activities typically create test plans, requirements, criteria, proce- 
dures, and test cases, which are set forth and agreed upon before testing actually 
proceeds. Test results are commonly documented in various reports. Delivery 
of software to a customer generally requires still more documentation in the 
form of configuration audits, version descriptions, delivery conditions, instal- 
lation plans and provisions, and maintenance agreements. Software sustaining 
and maintenance activities involve implementation of system changes and the 
maintenance of currency and synchrony among documentation elements and 
the system components. Potentially, conjunctive methodology can reduce effort 
and improve the quality of test documentation by reduction of redundancy and 
maintenance of currency. 
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2.3 The Conjoin Program 

The processing engine for conjunctive programs described in this report is 
Conjoin, which, in its present form, is a considerably less grandiose and ad- 
mittedly simpler tool than WEB or Intermedia. It is written in C, but could 
probably have been implemented as an additional macro package incorporated 
into T^X, had I been a more competent T^rjXnician. There may even be cut- 
and-paste programs that are already available on the market that would have 
saved me the trouble of writing the Co ijjoin program altogether. 

Conjoin requires only a minimal production environment: a text editor to 
create code, data, and documents; T^X, for document production; and a com- 
piler/linker, for translation to machine executable form. It replaces query direc- 
tives in the conjunctive program file with text copied from other files. Location 
criteria include the source file name plus either absolute locations within the 
file, string contexts within the file, or relative locations from string contexts. 

I had, at one time, thought of naming the conjunctive programming engine 
stitch, because it belonged in the same genre of names as WEB, TANGLE, WEAVE, 
and KNIT, the mainstays of literate programming. Conjunctive programming, 
however, is far more than just the “stitching” together of software artifacts, 
although that is precisely what the Coqjoin tool does. As in literate program- 
ming, the bulk of the effort is not spent in sewing, weaving, and knitting, but in 
composition. It is with the trusty text editor that the conjunctive craftsperson 
generates directives that sew extracted software and data elements into place, 
and it is here that the conjunctive artisan creates the narrative and graphic logic, 
justification, explanation, and other particulars that give tangibility, meaning, 
and worth to the finished product. Neither literate programming nor conjunc- 
tive programming can be characterized as word processing, even if that is where 
most of the practitioner’s time is spent. In order not to connote the mere me- 
chanics of the tool, but rather the method to which it contributes, I chose the 
name Coqjoin . 

2.4 Impacts on Method and Expression 

Conjunctive programming does impose a discipline on its practitioners. I re- 
alized this while developing the Conjoin program. My original intent was to 
provide a method of documentation that did not impact programming at all. 
I initially wrote a small prototype of Conjoin to assist simultaneous develop- 
ment of code and documentation. Other features were appended later, as the 
needs for them became known. Requirements for additional capabilities were 
also recognized, some of which are discussed in Section 6. 

After adding several features and modifications, I realized that synchroniza- 
tion between the conjunctive source and the accessed files is an essential need 
of conjunctive programming that is still not yet adequately robust. The pro- 
grammer is left responsible for creating and maintaining linkages between the 
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accessed code and other data files. No distinctive mechanisms that will be 
resilient to later changes are automatically provided. 

As Coi£7bin evolved, I realized that I was reworking parts of the program 
that already correctly functioned merely so that I could explain more easily 
how they operated. Just due to writing about it, the code was changing sig- 
nificantly in structure, although not in function. Additionally, I found many 
programming simplifications and subtle faults when describing the code. I thus 
relearned that the way one presents and describes programs influences the way 
one structures them. It is therefore not totally true that conjunctive program- 
ming is completely flexible and conformable to every mode of programming. 
Some adaptation within the practitioner inevitably takes place. 

2.5 Goals 

My reason for developing Coij7oin was pragmatic. I generally document the 
papers, reports, and programs I write using UTgX. The style of these documents 
appears very similar to that of this report. I had just completed a research 
effort resulting in the development and concurrent documentation of a tool for 
simulating the software reliability process [20]. In writing the documentation, 
I manually cut and pasted segments of the code with a text editor into the 
document. Keeping the document and the program code consistent was very 
time-consuming and unproductive. 

I needed something to extend the environment that I already had, and with 
which I was familiar — something that would adapt to my method and manner 
of expression. I did not want to learn another documentation system, nor did 
I want to reinvent the wheel. I wanted to have the code and documentation 
separate for ease of editing, compilation, debugging, and distribution. Having a 
program such as Coi£7bin would have served these needs and eliminated a great 
deal of frustration and rework. 

I began to apply Corbin by using only string-context searching to locate 
material for pasting into the document being written. I soon recognized the 
need for more a robust entity reference method as changes were made in the 
program. Slowly I began to introduce better anchors into the code, but only 
as needed. Wherever I applied more robust markup principles, the excerpt 
references proved to be more consistent. Elsewhere, I found that the extractions 
proved to be more fragile to evolutionary changes in the artifacts. I am still 
learning the effective means for generating robust, yet convenient, markup. 

2.6 Relation to Literate Programming 

Literate programs are literal programs; that is, the program source itself is 
integrally bound within the document that describes it. Every operation and 
every declaration, however trivial or minuscule, must appear in the document. 
Literal programs are complete programs, even if narrative, tabular, and graphic 
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descriptions in the remainder of the document are incomplete, inaccurate, and 
unintelligible. The code appearing in the program document is the actual code 
that compiles and runs. 

Conjunctive programs, on the other hand, do not necessarily document an 
entire program, line by line. Those portions of code and other data that are 
displayed within the document are actual and current, as in literate programs. A 
HAKE program with dependency files maintains currency between the document 
and the source elements. As in literate programs, descriptions of excerpted 
system artifacts may be incomplete, inaccurate, and unintelligible. 

Both literate and conjunctive programs are (ultimately) processed by TfeX, 
so they both generate documents of high typographic quality. They both permit 
the creation of textbook-quality documents, when warranted. They both display 
segments of code interspersed with explanatory text, figures, and tables. The 
code you see in both documents is the actual program source code. The order 
of appearance of code segments in both documents is independent of the order 
in which these segments are presented to the compiler. Both have mechanisms 
that maintain currency between the program that is seen in the document and 
that which executes. Both are operated in an edit-compose-render sequence 
of steps where editing may be interactive, but composition and rendering are 
batch-mode processes. 

Both currently suffer from a number of disadvantages, some of which are 
technology related: 

(1) Each is constrained by the limitations of the document processing system 
and the program development environment. 

(2) Both need better means for displaying figures and graphics, and neither 
supports a graphics-based design methodology very well. 

(3) Neither is oriented for WYSIWYG 3 operation. An interesting experiment 
would be to adapt Conjoin for use in a WYSIWYG environment, such 
as Ventura Publisher [21], which also uses a rather simple hidden- text 
markup that is consistent with the Cortfoin program design. 

(4) Both have been applied only to traditional types of systems and products. 
For large programs, document indexes, tables of contents, and lists of 
figures may not be as useful as online documents with automated display, 
search, and interaction tools. The current documentation trend is toward 
distributed heterogeneous multimedia systems incorporating hypertext. 

These problems can be overcome by enrichment of concepts, tools, and practices 
that will take better advantage of the evolving technology. 

Conjunctive programming may offer some advantage over traditional literate 
programming in the following ways: 


3 What You See Is What You Get. 
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(1) It can adapt to the way people now develop systems. The order of code and 
documentation development, the separateness of the artifacts produced by 
these activities, and the content and level of document detail can be tai- 
lored to project and individual needs and existing organizational standard 
practices. 

(2) It works conceptually with all programming languages that permit embed- 
ded comments and document generators that allow hidden text. Devel- 
opers already familiar with a documentation system do not have to learn 
another system. 

(3) It is applicable to retro-engineering efforts with no additional risk to the 
system operation. 

(4) It can be used to facilitate concurrent engineering and other forms of 
collaborative activity, because it can make the documentation and other 
products of all the teams accessible to everyone without requiring any 
changes in existing software responsibilities. Programmers can be separate 
from documentation personnel, and both can maintain cognizance over 
their separate charges. 

(5) It can be used throughout the life cycle, not only for program documen- 
tation, but for all kinds of project artifacts that integrate information 
from multiple sources. Markup standards and change notification proce- 
dures can be made a regular adjunct to project implementation plans and 
practices. 

(6) It can use existing development environmental tools, such as symbolic in- 
teractive debuggers, text editors, and program analyzers. CoijT&ixi does 
not have to duplicate the functions that commercially available tools al- 
ready have, but may incorporate their results. 

(7) It promotes reuse of existing code, data, and documentation. This reduces 
“waste” in the Total Quality Management [22] sense. 

(8) In cases where the copious display of code in a document is not required 
or desired, conjunctive programming can just provide specifications, ex- 
planation, and a bridge into the pertinent portions of code and data. For 
example, maintenance personnel claim they prefer reading code in source 
form once they have an understanding of the program, a road map into 
the code, and access to explanatory documentation, when needed. 

I can also see several disadvantages in conjunctive programming, among which 

are 

(1) There is no automatic assurance of completeness, when such is desired. 
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(2) There may be a loss of currency in documentation if program elements 
change without reMAKEing the documentation. 

(3) It does not promote structured design and structured programming as well 
as literate programming. 

(4) Corffoin does not automatically generate indexes and cross references, nor 
does it automatically format the resulting document as well as WEB does. 


j 
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3 USING Conjoin 

A Conjoin program is a text file formatted for processing by a markup document 
compiler or generator. As currently implemented, Corffoin programs produce 
©TgX documents; other dialects of TeX, such as -4 x<S-TeX and others > can 
conceivably also be accommodated, although this has not yet been done. This 
report was produced using JATgX, augmented by additional style markup com- 
mands particular to this report. 

Nothing in the conjunctive programming concept mandates the use of TgX 
or its dialects, but the power provides to the conjunctive programmer offers 
a considerable incentive. The CoQ^oin program has been structured to adapt 
to other T^X-like document-producing engines by run time markup directive 
redeclarations and recompilable definitions. Adaptation to the UNIX troff 
system or to Xerox’s Ventura Publisher, for example, are possibilities for study. 
1£X is used hereafter to illustrate the character of conjunctive programming as 
(dis)colored by my own personal preferences, habits, and skills. 

Currently, there are only two dependencies in Coi£7oin on T^X that are 
not changeable via run time directives. These are the T£X comment-initiation 
string, used by Coitfoin to initiate its directives, and \verb| text] used to 
enclose in line verbatim text. Such dependencies are localized in the program as 
macros that can be redefined to the equivalent commands of another document- 
generating engine. 

3.1 The Source File(s) 

The Cozj/oin tool copies a user’s source file, assumed to be an ASCII text file, 
line by line, directly into a target file. It is not essential that all the characters 
in the text lines be printable characters, as long as a newline 4 appears regularly 
within the maximum line length allocation. The lines are assumed primarily 
to be made up of “regular text,” or text that will be recognized and processed 
by the documentation system (i.e., IAT^X in this report). In addition to this 
regular text, there are 12 directives that are specially recognized and processed 
by Cortfoin. These ail begin with the target-processor comment signal string (for 
T^X, so that the user source could conceivably be processed directly by 

the target processor, except that none of the Coi£7<oin directives nor their effects 
would appear in the compiled document. Rather, the user s source file directs 
the integration of information segments from many heterogeneous sources into 
a target file that is then processed by the target processor (T^X or I^TeX, et 
al.) in the normal fashion. 

4 The meaning of newline is generally implement at ion- defined. Some systems use a com- 
bination of carriage return (CR) and line feed (LF) to mark the end of a line, while others 
use LF/CR or just one or the other by itself, and some have other special conventions. This 
need not be a problem, as long as the text editor, Conjoin, *nd the document generator all 
recognize the same convention. 
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The length of text lines in the Covffoin source file is limited by the value of 
the HAX_LIHE macro within Coxff oin program, 

#define MAX.LIHE 135 

Each CoTffoin directive, except ‘/.size, is copied intact into the target file. 
Since these are formatted as comments, they will not be seen in the document 
being created. Each directive, except %size, should appear on a separate line in 
the source file, and may not exceed one line in length. The %size directive may 
appear anywhere within ordinary text. The £oi£7&in directives are sensitive to 
capital and lowercase alphabetic characters. 

The directives in alphabetic order are; 

• '/.access filtjname break^string $tart_string range _scparaior end^string 

• '/.break break^strxng 

• '/.column stari_column _ 

• '/.count couni_sxgnal 

• '/.garbage subsiitutxon_char 

• '/.path directory 

• '/.postfix en<f_eni?t?x>nmenf 

• '/, prefix begin_envxronment 

• '/.range range ^separator 

• '/.show { on I off > 

• ’/.size { C I a I T I r> 

« '/.tabs iabjwidih 

Each of these is described in detail in this section. Path and file names used in 
the examples are shown in MS-DOS style. 


3.2 Selective Inclusion of Text Files: ‘/.access 

The workhorse of the Coi£7oin program is the '/.access directive that selectively 
locates, copies, and formats text from files by using the environment set by the 
'/.preiix-'/.postiix pair. Most of the material displayed here in the TgX \tt 
font was '/.access-ed from system objects. 
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For example, the definition of the constant MIL in the Coiffoia program may 
be printed by accessing the context of the ♦define statement, 

%access Conjoin. c, deiine HIL+O " 1 

(note that the character ♦ does not precede define in the ^access directive 
because ♦ is the default count_signal, described later). Coi^oin responds with 
the result 


♦define HIL ((void *) 0) 

Coq7oin supports three kinds of location markup tagging: 

(1) by context (as above) 

(2) by line position in the file 

(3) by line position relative to a context 

This markup recognition is not as general as that offered by a Hy Time-compliant 
engine, and may be augmented in future versions (see Section 6). Coiffo in can 
find contextual keys in the system database, either occurring naturally or placed 
there as anchors for more robust access. As a result of my using both approaches 
in describing the Conjoin program in Section 7, I now recommend that users 
embed unique, standardized anchors in the system database that will withstand 
system evolution. However, all three reference schemes will be explained below. 
The syntax of the directive is 

'/.access file_name break_stnng start ^string mnge_separator end_string 

The filename identifies the name of the file in which the text segment to 
be copied may be found. The break_string is by default. The optional 
siart_siring and end_string take the form 

\.maich_siring] icount_signal count ] [± 0 j(fse<] 

In each case, the match_stnng is a set of substrings, separated by break_string, of 
characters to be matched exactly (case sensitive) within the named file, in order. 
That is, matches for each substring are sought in the order given. Subsequently, 
the offset is an integer number of lines past or before the string match condition. 
The count, when present, is always considered positive and denotes the number 
of matches necessary to start action. The default count is one. The number of 
substrings is limited in number to 

♦define MAX.COHTEXT 10 

If the starting match^strxng is missing, then the match condition is satisfied 
at the beginning of the file. A default offset of unity is presumed if the starting 
offset is missing. A unity offset causes all lines up to and including the matching 
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line of the named file to be skipped. Setting the offset to +0 prints the line 
fulfilling the string match condition, and a positive starting offset of n causes n 
lines in addition to the matched line, to be skipped. 

Negative offsets are also permitted. Setting the beginning or ending offset 
to -n causes the action to take place n lines before the fulfillment of the string 
match condition. It is necessary, in this case, that Conjoin maintain a queue of 
length n, which is limited in size to 

#def ine HAX_Q 100 

If the ending match_siring is present, but the offset is missing, an offset value 
of -1 is assumed. Coi£7oin stops copying at the line matching the match^stnng 
condition in this case. Setting the ending offset to +0 causes the line fulfilling 
the match_sinng condition to print. 

If the ending match^string is missing and the ending offset is non-positive 
(the default when missing is -1), copying extends until offset lines prior to the 
end-of-file. If the ending maich_string is blank, but a positive offset is present, 
that value specifies the number of lines that will be copied from the named file. 

The + in a positive offset may be omitted when the match_string and count 
fields are absent. The - in negative offsets must always appear. 

The range separator default * between the beginning and ending extraction 
keys above can be replaced, if desired, with a more convenient mark by using 
the '/.range directive described later in Section 3.9. The count_signal default # 
that signals the beginning of the count field may also be changed by using the 
'/.count directive described in Section 3.5. 

A typical usage of the '/.access directive is illustrated in the following: 

'/.access Conjoin. c, * strext *+0 " * end strext *+0 

which produces 

/* strext */ 


sTftxsc " . 

strext (s, t) /* Extract string t up to the close-co*wnt string, if close 
is not null, or to the end of t if null, into s. ReaoTe 
leading and trailing blanks from s and return s. 


STRUG s, t; 

{ 

STRUG p; 

if (*close AID Cp » strstrCt , close))) 
strtcpyCs, t , p - t) ; 

else 

strcpyCa, t) ; 
return stratrim(s) ; 


/* end strext */ 


> 
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As seen above, this usage copies all lines between the first occurrence of a line 
containing the beginning markup anchor substring * strext + and the next 
occurrence thereafter of a line containing the ending markup anchor substring 
* end strext *, inclusively, into the target file. The result in the target file 
is the source code for the strext () function shown below and explained more 
fully later in Section 7.19. 

Insertion of */,ac cess-linkages into the code in the form of distinctive com- 
ments, such as * strext * and * end strext * above, brings a measure of 
robustness that is not found with other contextual means of location. Synchro- 
nization among conjoined files and ^access directives is made more reliable 
when separate markup is provided. Other means of text segment location, such 
as by match count and ofTset, are much more fragile to changes in and move- 
ment of code functions. Section 6 discusses possible future enhancements in 
conjunctive programming tools that will promote further synchrony. 

When the +0 offset designations in both the beginning and ending search 
strings are omitted, the result is 




STRUG 

str«xt (s , t) f+ Extract string t up to th« closs-conent string, if close 
is not null, or to the and of t if null, into s. Remove 
landing and trailing blanks from s and return s. 

/* •/ 

STRIVG s , t ; 

{ 


STRUG p; 

if (*close AID (p * strstr(t, close))) 
strtcpy(s , t , p - t) ; 

else 

strcpyCs, t); 
return stratria(s) ; 

> 


The file segment could have been displayed just as well by using a negative 
beginning offset, 

^access Conjoin, c, strext ( #9 -2 * 16 

or using an ending search string that stops 3 lines earlier than the next function- 
header-line, 

access Conjoin, c, strext ( #9 -2 “ ***** #2 -3 

because the strext () function appears on the ninth appearance of the name 
in the program file. This method is not recommended, as it is very sensitive to 
future changes in the program code. 

Multiple substring context matches can also be specified as a means to avoid 
ambiguity in locating a desired point in a file. As an example, the appear- 
ance of close in the code segment above can be located by first searching for 
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* strext ♦, then bypassing the appearances of close in the function descrip- 
tion by looking for STRUG p, and finally, by seeking the next appearance of 
close. The '/.access directive is written 

'/.access Conjoin. c, * strext *, STRUG p, close +0 ' 1 
which results in the single line 

il (*close AID (p = strstrft, close))) 

Note: If a match_string contains either + or then it is necessary to apply 
the count^signal so as not to mistake the sign character for the start of an offset 
count. For example, to access only the function banner portion of the strextQ 
module, one could use 

•/.access Conjoin. c, * strext * ” /* #1 + 0 

3.3 Setting the Context Separator: Jibreak 

The default delimiter for file names and matck_stnng in the '/.access directive 
is the comma character, This can be changed by using the directive 

•/.break break_stnng 

The default is thus equivalent to the statement 

•/.break , 

The breakjtrxng may contain any (non-null) characters, including embed- 
ded white space, but any leading and trailing white space is removed. The 
break_stnng and the range_separator must be different (for error detectability 
reasons), and these must differ from the count_signal, +, -, and all characters 
that appear in the match_$trings . 

3.4 Setting the Alignment Column: ^column 

If, at times, the '/.access-selected text has too little or too much white space to 
the left of the lines to be printed, an alternate starting column can be selected 
by the directive 

'/.column start^column 

The stari column may be positive (added spaces) or negative (deleted charac- 
ters). The default starting column is zero, so the default is equivalent to the 
directive %column 0. 

As an example, the Coq/oin program contains a code segment that appears 
in the Conjoin. c file as 

if (I0T Ctrqueu* [q.r] » strdup(t«it) ) ) 

{ «rror_MS*.g.(HEMORY_EIlR. FALSE); 

•rror * TRUE; 
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break; 

> 

Using a '/.column -16 directive causes the output to take the form 

if (I0T (txqueue [qex] * strdup(text) )) 

{ «rror_»esBage(MD10RY_ERR, , FALSE); 

error ■ TRUE; 
break; 

> 

The alignment column remains in effect until reset by another ^column directive. 

3.5 Specifying the String Match Count Signal: ’/.count 

The beginning and ending '/.access string matching specifications may, at times, 
themselves contain the default match-count-signal, #. In such cases, the match 
count signal may be changed by using the '/count directive 

%count couni_signal 
The default is thus equivalent to 
•/, count # 

The break_$tring and the range^separat or must be different (for error detectabil- 
ity reasons), and these must differ from the count_signal , +, and all characters 
that appear in the match_stnngs. 

Examples of the use of the count^signal appeared earlier, in Section 3.2. 

3.6 Conversion of Non-Compilable Characters: ^garbage 

Text files occasionally contain non- ASCII characters (such as those of the IBM 
character graphics set) that cannot be printed by the target processor. In such 
cases, Coiffoin makes a substitution. All non-printable characters are replaced 
by a “garbage” character, which by default is #. This default can be changed 
by using the directive 

^garbage sub$titution_character 

The substitution^character remains in effect until reassigned by a later ’/.garbage 
directive. If no substitution character is named, no substitution is made. No 
provision is currently available in Coiffoin for character translation other than 
this simple indication of where non-printable characters have been encountered. 
The default is equivalent to 

’/•garbage # 

As an example, all the files describing and comprising Corffoin contain a 
copyright header that contains graphic characters recognized by most IBM- 
compatible printers, but not by T^X. When Coq7oin-ed, this banner appears 
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When viewed by a text editor or as a direct-dump printout, the garbage char- 
acters above form a double-line box around the notice. 

3.7 Setting File Search Paths: '/path 

When text segments to be accessed are in a directory other than the current 
default path, or if segments are to be copied from files in several directories, 
these paths may be identified by using the ‘/path directive, 

'/.path directory 

Paths remain in effect throughout the remainder of the Coiffoin file. 

Any number of path directives may appear, up to the maximum number 
defined in the Coxffoin program, currently 

#define NUMBER_OF_PATHS 20 

The benefits of the '/.path directive are that its usage can help make doc- 
ument files more portable and adaptable to multiple platforms, permitting lo- 
calization and concentration of search directory specifications, thereby reducing 
the sensitivity of the document to path-naming conventions. Furthermore, it 
also shortens file names appe aring in ^access directives. 

An example of the '/path directive usage is the following: Several functions 
accessed by the Coi^oin program are located in a separately compiled library 
for which the source code happens to be available. This code appears in the 
directory \c\tppc\c, which, as one may easily guess, refers to “Tausworthe’s 
Own Personal C” library (TOP-C). 

'/access \c\topc\c\stratrim. c , *****+0 

Alternately, one may use a '/.path statement to identify the library directory, 
'/.path \c\topc\c\ 

'/access stratrim.c, *****+0 

Note that the final directory separator (here, \) is necessary in the '/.path state- 
ment, as path strings are directly concatenated with the accessed file name in 
searching for the file. 
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Either of these two alternative forms transcribes the same file segment into 
the target document: 


STRUG 

stratriaCs) /* Tri* all whit* space froa a, leading and trailing, and 

then return s. 


STRUG s; 

{ 

FAST STRUG p; 

p * strfnb(s) ; 

strtcpy Cs f p, strlen(p)); 

return strtria(s) ; 

> 

3.8 Setting the Environment: '/.prefix and ^postfix 

The environment for printing the text selected by the ’/.access directive is con- 
trolled by %pref ix and '/.postfix directives: 

'/.prefix begin^environment 
•/.postfix end^environmeni 

where the beginning and ending environment portions of the directives are 
target-processor commands that set up and terminate the environment for print- 
ing '/.access-ed text. The defaults are equivalent to the following directives, 
which enclose the J£TgX verbatim environment: 

'/.prefix {\f ootnotesize \begin{ verbatim} 

'/.postf ix \end{ verbatim}} 

These defaults print the intervening text by using the \tt font, sized small 
enough that an 80-character line fits into the width of a printed page. Lines 
appear in the output document exactly as they do in the text file. Coq/oin does 
not perform “pretty printing” of the selected text. The regular font style and 
size environment are restored by the '/.postfix statement. 

Selected beginning and ending environment statements stay in effect until 
changed. 

3.9 Defining the Access Selection Separator: ’/.range 

The default * separator appearing in the description of the '/.access directive 
above may not always be effective to use, such as when a desired starting 
match string contains a " character. The default may be overridden by the 
directive 

'/.range range_separator 

All leading and trailing white space in the range ^separator are discarded by 
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Coxffoin. The rangeseparator remains in effect until changed by another grange 
directive. The default is equivalent to 

•/.range ’ 

The break_siring and the ran gejeparator must be different (for error detectabil- 
ity reasons), and these must differ from the couni_signal , +, and all characters 
that appear in the match^string s. 


3,10 Displaying the Corffoin Directives: ’/.show 

£on7oin directives, except '/.size, can be displayed in the target document by 
using the '/.show directive, 

•/.show { on 1 off } 

When on, each occurrence of a Copjoin directive is made visible in the target 
output file. The action of the directive takes effect immediately. 

The directives used to display the HUMBER.OF.PATHS definition in Section 3.7, 
for example, were 

•/.show on 
•/.column 8 

'/.prefix {\begin{ verbatim} 

'/.access Conjoin. c, NUMBER_0F_PATHS+0 ~ 1 

#def ine NUMBER_OF_PATHS 20 

'/, column 0 

'/.prefix {\footnotesize \begin{ verbatim} 

•/.show off 

The display setting persists until reversed by another Xshow directive. The 
default is equivalent to 

'/.show off 


3.11 Displaying File Sizes: Xsize 

Each time Cor^oin is run, a file having the same name as the target file, but 
with a .siz file type, is written that tells the total numbers of lines 

(1) in the Conjunctive program source file 

(2) transcribed into the target file by '/.access directives 

(3) written to the Target file 

(4) the ratio of the latter two 



92-12 


27 


These numbers are available via '/.size directive, which may appear anywhere 
within a line being processed. The syntax is 

•/.size {C I a I T I r } 

The options, C, a, T, and r may appear either capitalized or uncapitalized and, 
respectively, correspond to the four items above. Since the items refer to the 
sizes of the file when it was last processed, there may be an error if the number 
of lines has changed. To avert this possibility, Cortfoin should be run at least 
twice before processing by T^X. 

As an example, '/.size is used four times in the following sentence where 
underlined: The last time Cot^oxti processed the CJ_body.CJn file, it contained 
3159 lines, which transcribed 1 184 lines from other files into the target file, to 
produce a total of 4351 lines in the target file. The extra 8 lines in the target file 
over its constituents is an identification banner, described later in Section 7.15. 
The ratio of transcribed-to-total lines is 0.272 . 


3.12 Altering the TAB Width: */ ( tabs 

By default, tab characters in the '/, access-selected file are expanded to align 
text on columns 8 characters wide. This default may be overridden by using 
the '/.tabs directive, 

'/tabs tab_width 

The default is thus equivalent to 
'/.tabs 8 

The TOP-C library function strtcpyO with '/.tabs 4 in effect displays as 

/♦MM* MM MM 

STRIIG 

strtcpyCs, t, n) /* Truncated string copy. Copy at most n CHIRs 
of t into s, and return s. lote: in contrast 

to stmcpyO, the returned copied s always ends 
in IUL . 

/♦ */ 

STRIIG s ; 

const STRIIG t ; 

size.t n; 

{ 

size.t m; 
if (s) 

{ m ■ strlen(t) ; 
n ■ HII(n, m) ; 

■emnoT« ( s > t, n) ; 

*(s + n) » IUL; 

> 

return s; 
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The same code with the default 7, tabs 8 in effect appears later in Section 8.7 
for comparison. 

The tab width remains in effect until altered by another Xtabs directive. 
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4 INSTALLING AND RUNNING CoTtfoin 

This section describes how to run CoTffo±n on the IBM Personal Computer, 
or compatible. It does not explain how to run either T^X or I^TgX or the C 
compiler. It is assumed that user guides are available for these and that the 
user is already familiar with their operation. To date, Con7oin has only been 
implemented for the IBM PC; however, the program is written in ANSI standard 
C, except for a few routines that have been accessed from my TOP-C library, 
which are included in a separate source file on the product disk. 


4.1 Configuration 

The Conjoin system described in this report requires the following environment: 

(1) An IBM Personal Computer, or compatible device with at least 128 kilo- 
bytes of available RAM for execution and utilizing the MS-DOS operating 
system Version 3.1 or later. 

(2) About 100 kilobytes of available disk or diskette space for system storage. 
Disk storage is preferred, and the system has not been tested for floppy 
diskette operation. Installation in the next section is limited to hard-disk 
configurations. 

(3) TfeX and DTgX (or other publishing system), text editor, and other doc- 
umentation tools, with the peripherals and storage they require. 

(4) If modifications of the system are to be made, a text editor, C compiler, 
and linker. The .bat and .mak files provided on the product disk are 
configured for Microsoft C 5.1, and for my directory structure and devel- 
opment system. These may have to be edited to conform to other compil- 
ers and user environments. Additionally, the top.c functions should be 
appended to the Conjoin, c file prior to compilation. See Section 9 for 
more information on program modifications. 

4.2 Installation 

The steps for installing the (Jor^/bin system are: 

(1) Create a (preferably separate) subdirectory, such as \conjoin, and make 
this the default directory: 

>md \conjoin 
>cd \conjoin 

(2) Copy all the files from the distribution medium into this directory. For 
example, if the distribution is a disk in drive a:, then 

>copy a:*.* 
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(3) Invoke Coij/oin with no parameters to see the usage message: 

99999999998999999999999999999999999998899889998998999999999999999989; 

* 

8 Copyright (C) 1992, California Institute of Technology 

# ill rights reserved. U. S. Government sponsorship under IASI 

8 Contract VAS7-918 is acknowledged . 

i 

8 Robert C. Tausvorthe 

* Jet Propulsion Laboratory 

• 4800 Oak Grove Drive 

8 Pasadena, Ci 91109-8099 


888tti9t888t88#8f9i8889f98fi888i88888888i8t8988tt899889889898888988889889; 

Conjoin Program 
(08-ipr-1992) 

Usage: Conjoin <ConJoin source> <target file> [<options>] 

Source file type default is .CJn 
Target file type default is .Tel 


Options : 

-a Do not announce the progri 

Cobb and line error: Vo source file named. 


This, or a similar message also appears whenever Conjoin detects a con- 
dition under which it cannot proceed further. 


4.3 Running Coi^oin 

There may be differences in running Coij7oin, even on the IBM PC, of com- 
patible, primarily in how execution is initiated and how files are specified. The 
description here outlines the operation in batch mode. Once Cotffoin is initiated, 
it reads its input files and writes its output file until completion. Selection of 
the files is made on the command line at the DOS prompt. Some implementa- 
tions may have menu- or window-based user interfaces that alter this procedure 
somewhat. The user is expected to know how to create the equivalent of a DOS 
command invoking Coiffoin and specifying its input, output, and options within 
the user interface of the platform involved. 

(1) File naming. The DOS operating system locates files by subdirectory 
“path” and by “file name” and “file type” (or “extension”) within a di- 
rectory. The user is expected to understand these general conventions, as 
they are not further explained here. Files input to and output by Coq/oin 
may be specified to have any subdirectory, name, and type. A missing 
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type in the input file specification defaults to .CJn; a missing output file 
type specification defaults to .TeX. Coxffoin creates a file with the same 
directory and name, but with type . siz that contains processing size 
information (see Section 3.11 for further information on access to this in- 
formation). CoijTbin also saves the previous output file, if one existed, by 
giving it a .T_X extension and removing the old .T_X file. 

(2) Building source (text) files. The generation of a T^X conjunctive pro- 
gram is almost the same as writing any other T^rjX document, except that 
when information from a system data file is needed, or if the information 
to be accessed is to appear in a modified format in the resulting document, 
then at these points, Coi^oin directives are used as heretofore described. 

To ensure that material be more easily or more robustly transcribed, the 
user may edit the source file to insert entity reference markup in the form of 
comments. Entity reference markup considerations are discussed further 
in Section 5. 

(3) Execution. While Corffoin may be operated from any directory as long 
as fully qualified path names are used to locate Cojj7oin, source, and target 
files, it is generally more convenient to change the default directory to that 
in which the files are found, 

>cd path 

Then invoke Coxffoin to process each conjunctive program by using 
>c :\conjoin\conjoin options source target 

The options may appear anywhere within the invocation, but the source 
must precede the target designation. The source must always be present, 
but options and target are optional. 

If target is omitted, a default name is generated by using the source name, 
but changing the file type to .TeX (current default). 

Only one option currently exists: -a, which causes the JPL/Caltech copy- 
right announcement, program name, and version date to be omitted. Pos- 
sible future options are described in Section 6. 
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5 FURTHER CONSIDERATIONS 

The continual, elaborate, and extensive flow of electronic documents within and 
throughout industry, universities, and government agencies has created version, 
review, revision, and currency problems for nearly everyone involved. Authors 
often create multiple versions of a document for different purposes (full report, 
literature paper, executive summary, etc.), to be communicated broadly and 
to be viewed via e-mail, printout, video, and typeset media. When comments 
and responses received from multiple sources must be matched to the versions 
reviewed, all the information communicated must be managed in an orderly 
way. This section discusses three areas where care and thought must be applied 
in the conjunctive documentation life cycle: organization, linkage markup, and 
retro-engineering. I deem these areas important because of the lessons I learned 
in developing this report. 


5.1 Document Organization 

This publication, in its current form, is the integration of many files conjoined 
for T£X processing. The top-level master document file shown in Appendix B.l 
controls the integration of the many separate, constituent components that make 
up the report. Appendix B.3 shows how the call-tree of Appendix C.l and the 
reference list of Appendix C.2 are made each time the Conjoin, c program 
changes. The document MAKE file in Appendix B.6 directs the generation of 
the program size file, the translation of .CJn forms into T^jX files, and the 
subsequent production of the report by T^X. 

The report structure is formed as it is because other documents are, or are 
planned to be, constructed from the same baseline files by inclusion, exclusion, 
and '/, access. The markup and composition techniques that have been employed 
did not originate with this aim in mind, however, and for lack of my attention, 
do not yet entirely fulfill this goal. Some rules for promoting currency and 
synchrony have been relearned and reappreciated during the writing of this 
report: 

(1) Design the documentation using object-oriented concepts. Organize ma- 
terial into separate, cohesive objects. Establish classes of items within the 
system that will promote stability of products during an evolutionary life 
cycle. Access entire objects to the extent feasible. 

(2) Plan to develop separate volumes of product documents from a common 
database of information from the beginning. Design the documentation, 
code, and data schemata to accommodate multiple views (subschemata) 
of product documents. 

(3) Separate document style design from document content design. 
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(4) Use aliases in source documents that will substitute application-specific 
expressions in output documents. Localize the definitions of aliases into 
a separate object for that application. In particular, use aliases for all 
“magic numbers,” or arbitrary constants that might eventually change 
over time or across documents. As an example, a I^TgX command \work 
was created to denote the current document type, here “report.” Every 
appearance of the word report in this document traces to an appearance 
of \work in the source file. 

(5) Use syntactic and semantic location mechanisms to refer to internal doc- 
ument structural entities (sections, subsections, bibliographic citations, 
etc.), rather than absolute positional information. 

(6) Use standard document types, outlines, and templates, when available. 
This often prevents having to “reinvent the wheel” when designing the 
documents in a new project. 

5.2 Entity Reference Linkages 

The successful evolution of conjunctive programs hinges on the query techniques 
used to access information from system code and data media. All conjunctive 
programming engines must support persistent tagging of information for query. 
(In hypertext and HyTime, linkage tags are called anchors .) Code units to be 
located by queries range in hierarchy from directories, to files, to functions or 
declarations within files, to clauses within them, to statements or lines within 
clauses, and finally, to atomic units (numbers, words, or other tokens). Similar 
hierarchies apply to other forms of information. Synchronism between copied 
information and the document context tends to decrease as the granularity 
increases. That is, the content of 4 lines of text starting at the first occurrence 
of the token “5” in a particular file is apt to be much more contextually variable 
than is, say, an entire function. It is true that the function may change over 
time, but the document context probably still concerns that function, whereas 
the mere change of an earlier parameter value from 4 to 5 in the former case 
completely destroys the correspondence between the code and the document 
context. 

Queries may be made by using absolute or relative locations, contextual 
information, semantic content, or a combination of these. 

Linkages to items in an information base may be made on the basis of abso- 
lute and relative locations, context, and semantic content, in order of increasing 
robustness. Each form of link requires some form of query processing. For 
absolute and relative locations, mere counting suffices. In the case of context 
queries, string matching or pattern recognition may be applied. Searching for 
semantic content requires a system capable of interpreting the data it encoun- 
ters. CoTffoin accommodates the first two types of linkages in the form of an 
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absolute count of sequences of matched patterns followed by relative count of 
lines. 

Linkages to textual items can be made purely on the basis of location and 
context information alone if desired. However, the use of distinctive markings 
within the data purely for the purpose of establishing such linkages can produce 
a much more robust synchronization between the referenced information and 
the document context. Inserting linkage tags in code and data files may require 
agreements with the owners and/or managers of those objects. However, the 
minimal extra effort required during implementation to insert these marks may 
yield a significant payoff in documentation productivity later. 

Plans for making robust linkages should be considered early in the product 
life cycle. Projects or cognizant individuals may need to develop standard con- 
ventions for linkage markup, or may apply standards, if available. The tagging 
should be distinctive and recognizable as linkage markup. It should have both 
beginning and ending delimiters (these are useful for location, modification, and 
removal, when needed). 

Cohesive segments should be tagged whenever it is likely that access will 
be made and location by the surrounding context is unreliable. In data where 
embedded markup is disallowed, such as in data managed by a database man- 
agement system (DBMS), other provisions may have to be made. For example, 
preprocessing the information using queries to a DBMS may be necessary. Al- 
ternatively, entity reference tags may be put into an auxiliary file and separately 
accessed via a special linkage engine. 

Robust markup works in both directions. Besides helping to synchronize 
working files and documentation, recognizable linkages help during maintenance 
in locating all the places in the documentation where descriptions of information 
may be accessed. When code changes, for example, the linkage provides clues for 
finding the corresponding narrative. Without recognizable markup, one is left 
with a somewhat more difficult search. When changes are made in a program 
file, one must search through all .CJn files for '/.access-es bearing the altered file 
name. Then, in those files, one must look for contexts consistent with material 
that was in the file before the changes took place. Some of this may be made 
easier by a utility program to print file differences, as a guide to where the 
changed areas are, and a utility program to trace '/.access conditions into the 
code to check whether the range intersects one of the changed areas. 

With distinctive linkage tags, however, one need only search for %access-es 
to the changed files bearing the matching tags in the areas of change. 

I had been working on the concept of conjunctive programming and the de- 
sign of Coiffoin for some time when the HyTime article appeared in the Commu- 
nications of the ACM [8]. I recalled while reading it that I had earlier reviewed 
a draft of the proposed Standard Generalized Markup Language for JPL a few 
years before and had since forgotten all about it. The ACM article made me 
suddenly realize that conjunctive programming is part of a much wider data 
interoperability discipline, one for which standards are emerging into practice. 
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Future work in conjunctive programming should investigate the use of the inter- 
national standard for SGML [9] in conjunctive programs and augment Coigfoin 
accordingly. 

5.3 Retro-Engineering 

The terms “retro-engineering,” “reverse-engineering,” and “re-engineering” have 
been assigned slightly different meanings by researchers and others, but those 
terms generally refer to efforts to redevelop quality attributes within existing 
products after they have been implemented. I will not distinguish among the 
subtle differences here. The process is one that involves recovering or improving 
the design and translating, restructuring, or augmenting the program code. 
Tools exist in some environments to create portions of the new documentation 
in narrative and diagrams— directly from scanning the code, while other tools 
assist in converting the code into required forms. Documentation educed from 
source code does not generate any new information about the code, although it 
may present data about the code in a more human-understandable form. Code 
translation can be slow, error-prone, inefficient, and costly. 

Problems in retro-engineering tend to fall into one of the following areas: 

(1) Implementation bias — recovery of general design information, rather than 
language and system considerations, from available information, is difficult 
and requires careful analysis. 

(2) Traceability— links between recovered information and original sources is 
needed for tracking completeness, consistency, and fulfillment of objec- 
tives. 

(3) Domain knowledge — the purpose, precision, range of values, rationale, the- 
oretical basis, and significance of entities are missing and must be recre- 
ated. 

(4) Code correctness — latent faults may be duplicated into the re-engineered 
products. 

(5) Information credibility — defective comments and documents may be used 
to re-engineer products, and faults in the code may make documentation 
untrustworthy. 

The tools available for retro-engineering are generally the same as those that 
support forward engineering. They can produce dataflow diagrams, control flow 
diagrams, structure charts, data structure diagrams, entity-relation diagrams, 
state-transition diagrams, and online dictionaries, and they can produce doc- 
uments, analyses, and measurements. However, even though efforts may be 
significantly assisted by the use of automated tools, retro-engineering remains 
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largely a human task of supplying information, structure, and capability not 
otherwise derivable from existing products. 

Conjunctive programming can be useful in generating traceability links, 
recording recovered design and domain knowledge, conjoining appropriate por- 
tions of original and newly developed artifacts, and preparing the documents 
required. It can contribute to productivity by recording the recovered design by 
using media specifically developed for handling documents and linkages among 
information entities. Conjunctive programming should be particularly effective 
in efforts involving redocumentation only, because existing artifacts may not 
have to be altered at all. 
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6 FUTURE USAGE ENHANCEMENTS 

The simple capabilities of Conjoin discussed in Section 3 merely hint at the 
utility of tools in support of conjunctive programming. The present section 
discusses additional features and tools that may be developed if the (Joitfbin 
prototype is successful in garnering the attention of users at JPL or in NASA, 
other government agencies, or industry. The order in which these, or other 
functions suggested by users are developed, will be dictated by the needs of users, 
development costs, and availability of resources. Estimated effort for making the 
changes below also includes resources for review, test, and documentation. Costs 
estimated as "minimal” are expected to require a maximum of one workweek of 
effort. 

(1) A directive that is the same as ’/.access, but which does not insert prefix 
and postfix strings: ’/.use. This capability is available currently in Coiffoin, 
but is awkward, because the prefix and postfix must be nulled before and 
reset after using ’/.access. Cost: minimal, a few lines of code and 2 
subsections of user-guide documentation. 

(2) Provisions to permit matching leading and/or trailing blanks of entity 
reference strings. Cost: minimal, a few lines of code and alterations in the 
user’s guide. 

(3) Directives '/.open and ’/.close to change comment delimiter strings. Cost: 
minimal, a few lines of code plus a new section added to the user’s guide. 

(4) Directives '/.preshow and ’/.postshow to alter in-line verbatim command 
prefix and postfix strings. Cost: minimal, a few lines of added code and a 
new section added to the user’s guide. 

(5) A none option for the '/.show directive to prevent the copying of Corffoin 
directives into the target file. Cost: minimal, a few lines of code and a 
short addition to the user’s guide. 

(6) A directive /.ignore on I oil, or other such means to disable a directive 
without having to delete it. Cost: probably minimal, with only a few 
changes to Corffoin and user documentation, but some thought must be 
given to scope, exact syntax, and selection of ignored items. 

(7) Directives and command-line options to change all defaults, with an option 
to read command-line arguments from a file. Cost: minimal, a few lines 
of code each and a few corresponding changes to the user’s guide. 

(8) Directives for selective access to contents: directives, such as 5*includeif 
condition or ’/.excludeif condition . Details on just how this should func- 
tion must be worked out, especially with respect to the form of the logical 
condition. Cost: unknown, but probably could be completed in less than 
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three workweeks, one to work out details, one to make the changes, and 
one to develop the user’s guide material, if they prove to be useful and 
feasible. 

(9) Extension of the '/.size directive to permit access to other . siz files. Cost: 
unknown, but probably would require two workweeks, to work out details, 
develop code changes, and amend user’s guide material. 

(10) A means to reinstate initial defaults. Cost: minimal, a few lines of code, 
plus minor additions to the user’s guide. 

(11) Capability to push prefix/postfix pairs on a stack and to pop the stack 
back to a previous environment, or to define multiple environments. Cost: 
unknown, but probably would require less than 2 workweeks to work out 
details, develop code changes, and amend user documentation. 

(12) Better execution efficiency through slight algorithmic changes, such as re- 
taining open files to be accessed again, better pattern searching than from 
the beginning of the file each time, and creating variables to replace the 
various reevaluations of strlen(xx_SIGHAL) that appear throughout the 
program. Cost: unknown, but incremental improvements would probably 
require less than 2 workweeks each. 

(13) Improvement of program tolerance to changes by improving the cohesive- 
ness of functions and the removal of side effects. Some candidates are 
discussed in the Internal Operations Section, below. Cost: unknown, re- 
quires a more thorough evaluation of likely maintenance traffic. 

(14) Means for conjoining nested accessed files to an arbitrary depth. Cur- 
rently, only one level of conjunctive commands is accommodated. This 
feature would permit text segments accessed by Coiffoxn to contain fur- 
ther Con/oin directives. Cost: unknown, but would probably require less 
than 2 workweeks. 

(15) Directives to access the date and time stamps of files, and to make deci- 
sions based on these. Cost: unknown, requires more refinement of func- 
tional requirements. 

(16) Command line options to set all Coq/oin defaults. A command line option 
to input all options from a file; an option and directive to prevent Coi^/oiii 
directives from being copied into the .TeX file. Cost: minimal, only a few 
lines of code and minor changes and additions to the user’s guide. 

(17) Extensions to accommodate other document-producing systems, such as 
Ventura Publisher, and others. Cost: unknown, some study will be re- 
quired, but probably would require less than 3 workweeks, if feasible. 
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(18) A more integrated system of tools that would permit automated generation 
and maintenance of anchors and linkages, as in [10]. Cost: comparatively 
high, as initial acquisition costs of such a system are unknown. 

(19) A linkage manager that automatically registers the usage of conjoined 
segments of files and oversees the maintenance of anchors and objects 
within files. 

The progression from a simple tool, such as CoijToin, 1° the ideal conjunctive 
programming environment would require a more formal systems engineering ef- 
fort and a significant commitment of programming resources. Cost-effectiveness 
would probably be reached far short of the ideal system, after having acquired 
a set of tools that bridge the major difficulties in document creation and main- 
tenance. Some useful auxiliary tools that come to mind include 

(1) A coverage analyzer to assess the degree of completeness with which the 
conjoined document describes an entire program or set of programs. 

(2) A markup tagger with features for automatically generating robust entity 
reference anchors within programs and other files. 

(3) A tool to analyze programs and other files and to generate candidate 
linkages that should be made within a conjunctive program. 

Additionally, future efforts may convert the Corffoin system database into a 
form conforming to SGML and HyTime stand surds or to integrate with hypertext 
systems, such as Intermedia. 
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7 INTERNAL OP ER ATION S 

This section describes the Coitfoin program in a form as literate as is possible 
for me to produce in normal documentation time. The goal in normal documen- 
tation time is not necessarily to be literate, but descriptive and communicative 
to an audience with assumed skills and levels of expertise. In describing the 
program below, I have assumed that the reader is familiar with the ANSI stan- 
dard C language and its library functions. I will not explain the C statements 
nor the ANSI library functions, aside from their roles in the Corffoin program, 
when noteworthy. 

The £oi£7bin program itself does not currently fully conform to the SGML 
markup standards but does align with their goals. 

It is difficult without referees to know how much explanation is necessary for 
describing a program, even to an assumed audience, particularly one as short 
as this, having only 977 lines 5 of code. Is it necessary, for example, to tell 
a programmer why a C program includes stddef.h? Every C programmer is 
familiar with this header file and more likely has to be told if and why it has 
been left out, rather than why it has been included. Understanding what a 
program does and how it does it generally requires less information than the 
literate program, which must document every detail of compilable matter. 

However, for maintenance and reuse, it is necessary to know what use is 
being made of all information given to the compiler. For example, the Corffoin 
program at one time during its development referred to IMT_MAX, a value de- 
fined in limit s.h. A subsequent design improvement deleted that reference, 
whereupon it was possible to remove the corresponding #include statement 
from the code. Neither reader understanding of the functions and algorithms 
nor the computer performance was impaired by the unneeded #include in the 
program. Nevertheless, it was superfluous, outdated, and proper for exorcism 
by the attentive maintenance programmer (viz., me). 

In the remainder of this report I shall attempt to describe what I think a 
reader fluent in ANSI C should know in order to understand precisely what the 
Coiffoin program does, how it does it, and why it was constructed as it was. 

My particular manner of expression will be evident throughout the program. 
Although certainly influenced by the Plum Hall standards [23] of the early 1980s, 
my own style has evolved into a fairly consistent, somewhat distinctive set of 
practices and habits summarized below. Some may find fault with the form 
and composition, others will not. Practically all will notice, however, that it is 
distinctive. Whether this style would be effective if used by others is unknown. 
A bibliography of research in programming style appears in [24]. 

The point is that conjunctive programming and Coiffoin have permitted 

5 This number was %acctsa-ed from a file CJ_prog.siz using empty prefix and postfix 
strings (i.e., in a non- verbatim mode). The file was written by a utility program flints that 
scans the Coi£7bin program and records its length whenever Co^oin changes. This occurs 
automatically, directed by Bake. 
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me to express myself in text and in code in the way I wanted 6 for better or 
worse. The way I indent code in the source files is the way it appears here. 
Tortuously convoluted operations that appear nested within C if-constructions 
and elsewhere reflect the way that I think in code. I need documentation to 
help me after a while to unravel the intricacies of expression and to recall what I 
must have been thinking at that time — to revive the latent intellectual character 
of what would otherwise appear to be cryptic. 

As algorithms go, none in Coxffoin is particularly curious. In fact, every 
function seems perfectly straightforward — except for a few subtleties here and 
there that I hope will be clarified. My optimism is probably natural, since I 
have just recently written the program and it is still fresh in my mind. To 
become more sensitive to what this report should have contained, but does not, 
I will need feedback from others and an opportunity to redo it in a year or so, 
to provide the rationale now seemingly too obvious to be mentioned (but which 
will likely be evident by then), to correct misstatements, to include informative 
material obtained after publication, and of course, to update the narrative with 
descriptions of new and altered features. 

The degree to which the reader comprehends this report will measure the 
extent to which I have been successful in attaining my goals using conjunctive 
programming. Insofar as those goals have eluded me, I hope the reader will find 
the concepts and approach informative, or at least curious. 

The code for Coij/oin is contained in the file Conjoin. c, and is listed fully 
in Appendix A. The program displayed in this report should be viewed as 
the internal JPL prototype to illustrate conjunctive programming. Some of the 
enhancements discussed in Section 6 will probably appear in versions eventually 
released for wider usage. 


7.1 A Word on Programming Style 

This section is included not to defend my programming style but to explain 
what will be seen. The normal order of items in one of my program files is 

(1) Program header, with version, file name, copyright, and author declara- 

tions. ; : ■■ 

(2) Header files, in order as applicable: ANSI standard headers, ANSI-confor- 
mal library and macro headers, special system library and macro headers, 
and, lastly, system-dependent library and macro headers. 

(3) Local macro definitions, if any. 

(4) Global function prototypes not contained in include-files, if any. 

(5) Global data structures, if any. 

6 This is not so surprising, since I developed Coijjoin to do what I wanted. Hopefully, 
however, I have made it general enough to permit others this same freedom. 
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(6) Local function prototypes, if any. 

(7) Local data structures, if any. 

(8) Functions, in alphabetic or depth-first 7 order, except for mainO, which is 
always the first function. 

Each of these is displayed in a distinctive way. For example, the declara- 
tion of each function appears inside a banner (see the strextO function in 
Section 7.19) that consists of a right-justified comment containing the function 
name, followed by a distinctive, eye-catching row of asterisks. The function 
scope and return-type declaration appears on the next line, indented to empha- 
size the function name and parameters on the next line, flush left. An annotated 
description of the function and its return values, followed by a row of hyphens 
to enclose the description, end the banner. Parameter declarations appear im- 
mediately thereafter, followed by the curly-bracketed function code. 

No explicit function return type is specific if the default int applies. Simi- 
larly, int formal parameters are not declared. 

The function’s statements are indented as follows: Each level of statement 
logic indentation is one full 8-column tab, and each continued line is indented 
under its parent line by 4 spaces (a half tab). Each case of a switch () 
statement is indented 4 spaces from the switch on a separate line, and each 
case clause gets a full tab indentation. 

Blank lines separate return, break, and continue statements from suc- 
ceeding lines in functions and loops, except when the next line contains only 
a closing curly brace. In this case, the nearly blank line suffices to set off the 
early departure from normal processing. Blank lines also separate data struc- 
ture declarations from the algorithmic code and appear in other places where 
they seem to bring better clarity. 

Curly braces are always vertically aligned in function definitions, struct 
declarations, and nested control-logic, and usually also in data structure initial- 
izations. 

All macro definitions have uppercase identifiers. 


7 Functions in the Conjoin program file appear in depth- first order. 
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7.2 Program Preamble and ANSI Header Files 

The first block of code in the £oi$7oin program defines the program VERSIOI, de- 
clares the copyright notice string array, and invokes ANSI standard include-files. 
The array declaration at this point is not in the normal order of style described 
in Section 7.1; placed here, it serves both to display the copyright information 
that is required by JPL in its externally released software and provide a banner 
for announcing the program, when executed. 

•dafin* VERSIOI "(08-Apr-1992) " /• (Conjoin. c)*/ 

char copyrightnotice[l4] [76] * 

§n 

"• * » 

"* Copyright (C) 1992, California Institute of Technology t" , 

"t All rights reserved. U. S. Government sponsorship under IASA i", 

•»* Contract JAS7-918 is acknowledged. , 

#U 

"t * * 

>■# Robert C. Tausvorthe *"» 

"t Jet Propulsion Laboratory •” » 

»# ’ 4800 Oak Grove Drive 

»• Pasadena, CA 91109-8099 , 


"•♦♦••♦•••♦••••♦♦•••••♦•♦••••••♦•♦•••••••••♦••••••••••••••^•••♦••••••••••! 

}; 

/* 

AISI STABDARD HEADER FILES •/ 


•include <ctype.h> 
•include <errno.h> 
•include <stdlib.h> 
•include <string.h> 
•include <stdio.h> 
•include <time.h> 


Note, in this prototype form, the VERSION is identified by a date, rather than 
a release number. This date is automatically supplied by my (customized) text 
editor whenever I alter the file. The new date replaces whatever appears within 
the first set of parentheses in the file. The second parenthetical element is the 
name of the file, manually placed there for my convenience. 

The header ctype.h is included because it contains function prototypes 
and/or macros for isspaceO and isprintO, which are accessed by the func- 
tions fgetstrO (Section 7.26) and isdigitO, the latter of which is used by 
the access () function (Section 7.20). 

The string. h header appears because the function prototypes for strcatO , 
strchrQ, strcmpO, strcpyQ, strlenO, and strstrO are accessed in vari- 
ous parts of the program. 

The stdio.h header contains function prototypes and definitions of famil- 
iar input and output entities, such as fcloseO, getposQ, fgetsQ, FILE, 
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fopen(), fsetposO, perrorO, printiO, and stderr, scattered throughout 
the program. 

The time.h header provides definitions for the tm structure and time_t data 
type, and function prototypes for asctimeO, localtimeO and time(), all of 
which appear in the timestamp () function (Section 7.15). 

The stddel.h header file is not used, because the only useful element in it 
was MULL; however, MIL is used instead (defined in Section 7.3 below). 
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7.3 Definitions, Defaults, and Macros 

7.3.1 Synonyms 

Conjoin defines a number of data types, storage classes, constants, and opera- 
tors. 


typedef 

int 

BOOL; 

typedaf 

unsigned char 

CHAR; 

typedef 

unsigned char * 

STRUG; 

♦define 

GLOBAL 

extern 

♦define 

LOCAL 

static 

♦def ine 

IIL 

((▼oid *) 0) 

♦define 

IUL 

0 

♦def in* 

FALSE 

0 

♦define 

TRUE 

1 

♦define 

AID 

u 

♦define 

IS 


♦define 

I0T 

1 

♦define 

HOD 

X 

♦define 

OR 

II 


I adopted synonyms for the storage type macros extern and static, viz., 
GLOBAL and LOCAL, for some now- for got ten, but probably cosmetic reason, many 
years ago. GLOBAL data and functions are accessible by all program file elements, 
while LOCAL entities are accessible only within the environment in which they 
are defined. 

The null values NIL and NUL were defined for distinguishability among null- 
pointer and null-integer names. IS was defined because I was continually getting 
in trouble using = where == should have been (a carryover from programming 
in languages with no distinction between assignment and equality operators), 
and the other operators followed for similar reasons. 

7.3.2 Manifest Constants 

The manifest constants in Coq7oin are 


♦ifndef 

♦define 

FILEIAHE.HAX 

FILEIAMEJUI 

50 

♦end if 
♦define 

KAX.COVTEXT 

10 

♦define 

MAX.LIIE 

135 

♦define 

KAX.Q 

100 

♦define 

IUHBER. OF. PATHS 

20 

♦define 

PAGE. WIDTH 

75 


FILENAME_MAX is normally defined in stdio.h, as required by the ANSI 
standard. However, it does not appear there in the Microsoft C 5.1 used to 
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develop the program, so I have defined it conditionally here. MAX_LIHE is the 
maximum assumed length of a text line in a £oq7oin source file. MAX_Q is the 
maximum number of lines that may be queued, and thus the maximum negative 
offset for lines transcribed by the ^access directive. The NUMBER_OF_PATHS 
is the maximum number of y.path directives that may appear in a £oi£7bin 
program. The PAGE.WIDTH value is used by timastampO in writing the warning 
banner on the target file being produced (Section 7.15). 


7.3.3 Directives 

Since Conjoin directives are recognized and passed as comments to the target 
processor (TfeX), it is necessary for Corffoin to recognize the comment syntactic 
conventions of the target processor. Corffoin recognizes directives as specially 
formatted strings appearing between open and close markers, whose values are 
defined by 

•define OPEV.COHHEVT 
•define CLOSE.COKHEVT 
•define COKHEIT.LEVGTH 10 

These values are among the few in Coij/oin that are not alterable by run time 
directives options. They limit Coi^oin operations to T^X and its dialects. Other 
target processor comment delimiters can be accommodated only by recompila- 
tion. 

Next are defined the Con/oin directive signal strings. When these appear, 
the actions described in Section 3 take place. 


•define 

•define 

•define 

•define 

•define 

•define 

•define 

•define 

•define 

•define 

•define 

•define 


ACCESS. SIG1AL 

OPEV.COHHEVT 

"access" 

BREAK. SIGVAL 

OPEV.COHHEVT 

"break" 

C0LUHI.SIG1AL 

OPEV.COHHEVT 

"colu*n" 

COUVT. SIGVAL 

OPEV.COHHEVT 

"count" 

GARBAGE. SIGVAL 

OPEV.COHHEVT 

"garbage 

PATH. SIGVAL 

OPEV.COHHEVT 

"path" 

POSTFII.SIGVAL 

OPEV.COHHEVT 

"postfix 

PREFIX. SIGVAL 

OPEV.COHHEVT 

"prefix" 

RAVGE. SIGVAL 

OPEV.COHHEVT 

"range" 

SHOV.SIGVAL 

OPEV.COHHEVT 

"show" 

SIZE. SIGVAL 

OPEV.COHHEVT 

"size" 

TAB. SIGVAL 

OPEV.COHHEVT 

"tabs" 


7.3.4 Default Parameters 

Certain Coiffoin parameters earn be altered by directives; others may be changed 
only by recompilation. Values for most of these are discussed in Section 3. 
Defaults are 

•define BREAK. DEFAULT 
•define COLUHV .DEFAULT 0 

•define COUIT.DEFAULT "•" 
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•define GARBAGE. DEFAULT »*» 

•define OLD .TYPE.DEF AULT H .T_X" 

•define POSTFIX. DEFAULT "Wend” "{▼•rbati*}}" 

•define POSTVERBATIM "l\n\n M 

•define PREFIX.DEFAULT “{Wfootnotenize \\ begin {verbatim}" 

•define PRE VERBATIM "Wnoindent \\verbl" 

•define RAIGE.DEFAULT 
•define SHOW. DEFAULT FALSE 

•define TAB.DEFAULT 8 

•define TGT.TYPE.DEFAULT ".TeX" 

PREVERBATIM and POSTVERBATIM values are not discussed in Section 3, but they 
occur in response to the y.show directive to provide descriptive markup tag- 
ging for displaying commands in the target document. PREVERBATIM contains 
\noindent to make the directive print at the left margin, and POSTVERBATIM 
contains \n\n to place the ensuing text onto a new line. 

Error message strings are defined LOCALly within the eiror_message() func- 
tion (Section 7.10). Access to these is made by indices defined globally: 


•define BG I. HATCH. ERR 0 
•define BREAK. ERR 1 
•define CMD.LIIE.ERR 2 
•define EID.HATCH.ERR 3 
•define IO.SAHE.ERR 4 
•define MEMORY.ERR 5 
•define I0.ACCESS.ERR 6 
•define l0.C0PY.ERR 7 
•define RAIGE.ERR 8 
•define SIZE.ERR 9 


See the narrative for the error_message() function, Section 7.10, for a discus- 
sion of why this potentially fragile approach to error messages was taken. 

7.3.5 Macro Function 

The final definition is a macro for reading a message (msg) from the size-file 
stream, removing trailing white space (including newline), and saving it in 
malloc-ated memory. 

•define FGETSIZE(s) strdup(strtrim(f getsCs , MAX.LIIE, size. stream) ) ) 

7 A Function Prototypes for the TOP-C Library 

Earlier it was mentioned that several functions from the TOP-C library were 
accessed. Cozffoin provides function prototypes for these, 

GLOBAL STRUG stratrim(STRIIG) ; 

GLOBAL STRIIG strdup (STRIIG) ; 

GLOBAL STRIIG strfnbC STRIIG) ; 
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GLOBAL STRIIG 
GLOBAL STRIIG 
GLOBAL STRIIG 
GLOBAL STRIIG 
GLOBAL STRIIG 


str insert (STRIIG, STRIIG); 
strlvrC STRIIG) ; 
straset (STRIIG, int , int); 
strtcpy (STRIIG, STRIIG, int); 
Btrtrim(STRIIG) ; 


Source listings for these functions appear in Section 8. 
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7.5 Local Data Structures 

Despite the “global data considered dangerous” caveat of structured program- 
ming purists (which I consider myself to be, at least in spirit [25]), a few 
data structures accessible via the overall environment were considered neces- 
sary. These appear in a number of functions where accessing them as formal 
parameters would be awkward, unsightly, and distracting. The data are 


LOCAL 

long 

access. linos; 


LOCAL 

CHAR 

close [COHHEIT.LEIGTH] 

* CLOSE. COHHEIT ; 

LOCAL 

int 

column 

* COLUM. DEFAULT ; 

LOCAL 

CHAR 

Conjoin. rile [FILEIAHE.HAI] 

m IV 19 , 

LOCAL 

long 

Conjoin. lines ; 


LOCAL 

FILE ♦ 

Conjoin. stream 

• IIL; 

LOCAL 

STRIIG 

count signal 

« COUIT.DEFAULT; 

LOCAL 

BOOL 

credits 

« TRUE; 

LOCAL 

CHAR 

garbage 

- GARBAGE.DEFAULT; 

LOCAL 

STRIIG 

las t.acc .lines 

* IIL; 

LOCAL 

STRIIG 

last.CJn.lines 

* IIL; 

LOCAL 

STRIIG 

last.tgt. lines 

* IIL; 

LOCAL 

STRIIG 

last _ use .line s 

* IIL; 

LOCAL 

CHAR 

■ark [10] 

* BREAX. DEFAULT ; 

LOCAL 

CHAR 

open [COHHEIT.LEIGTH] 

« OPEI. COHHEIT ; 

LOCAL 

STRIIG 

path. list [IUHBER.OF.PATHS] ; 

LOCAL 

Int 

path.list.size 

- 0; 

LOCAL 

CHAR 

postfix [HAI.LIIE] 

« POSTFIX .DEFAULT ; 

LOCAL 

CHAR 

post eerbat im [30] 

■ PQSTVERBATIH; 

LOCAL 

CHAR 

prefix [HAI.LIIE] 

■ PREFIX.DEFAULT; 

LOCAL 

CHAR 

preeerbatim[30] 

■ PREVERBATIH; 

LOCAL 

CHAR 

range [10] 

- RAIGE.DEFAULT; 

LOCAL 

BOOL 

shoe 

- SHO V.DEFAULT ; 

LOCAL 

CHAR 

size.f ile [FILEIAHE.HAI] 

m llll. 

LOCAL 

CHAR 

spaces [HAI.LIIE] 

m II VI . 

LOCAL 

int 

tabeidth 

■ TAB. DEFAULT ; 

LOCAL 

CHAR 

tgt.f ile [FILEIAHE.HAI] 

M Mil m 
1 

LOCAL 

long 

tgt. lines; 


LOCAL 

FILE * 

tgt. stream 

- IIL; 


Data items that are not initialized above are set before use in the program. 
Many of the variables initialized here are Coq/oin directive defaults: column, 
count_signal, garbage, mark (used instead of break, which is a C reserved 
word), postfix, prefix, range, show, and tab_width. Default values were 
discussed in Section 7.3. Path specifications, named in path directives, will be 
entered into the path_list array, whose size, initially zero, is maintained in 
path_l i s t_s ize . 

The ConJoin_file string will contain the source file name obtained from 
the user-entered command line, and Con Join_str earn will designate the corre- 
sponding FILE * stream. The number of lines read from the source is counted 
by the variable Con Jo inclines; in the event this file is very large, the type has 
been made long. 
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The target file name is held in the tgt.lile string, and tgt.stream is the 
corresponding FILE * stream, when opened. The number of lines written into 
the target file by %access-es is access_lines, and the total number of lines 
written to the target file is tgt_lines, both long. All three numbers of lines 
are written to the file named by sizejf ile; these numbers will be read into 
the variables last_CJn_lines, last_acc_lines, and last_tgt_ lines when 
Cox$7oin next processes the same source file. 

The “announce” option, enabled by an -a entry on the command line, sets 
the BOOL variable credits FALSE, thereby suppressing printout of the program 
copyright notice, name, and version number in the announceO function of 
Section 7.9. 

The two string variables preverbatim and postverbatim are unchanged 
once initialized in the program, so macro constants could replace them in the 
code (see Conjoint ilesQ in Section 7.17). Since these are references to 
I^TgX- depen dent strings, they are candidates for initializationQ-alteration 
in future versions, should that appear beneficial. If this need ever arises, it is 
an easy matter to replace the variables with macros. 

The same is true of the variables open and close, which contain strings that 
open and close comments in the target-processor language. 

The variable spaces is a string used by ConJoin.f iles() , putlineQ, and 
timestamp () functions for spacing lines of output to the target file. 
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7.6 The mainO Program 

The mainO function of the (Joitfoin program is fairly short, 


iain(argc, argr) /• ProctM a Conjoin fila to croata a targat fila. 

iut ura a FALSE tsIus if no fsilurs occur*, or 
TRUE or othsr nonzero Talus if a failure »** 
encountered. 



SIRIIG argTC ]; 


BOOL failure j 

FILE Tsiza.strsam; 
int i; 

initializationCargc, argr); /♦ terminates if no source file named */ 

open.io.f ilesO ; /* terminates on failure in opening file* */ 

access.lines * ConJoin.lines ■ tgt.lines * 0; 
timeatampO ; 

failure * ConJoin_f ilesO ; 

failure |> fclose(ConJoin.stream) I fclose (tgt. stream) ; 
for (i * 0; i < path.list.siz# ; i++) 
free (path.l 1st [i] ) ; 
free (last. acc. lines) ; 
free (las t.CJn.lines) ; 
free (last .tgt.lines) ; 
free (last. use. lines) ; 

printf ("Processed: \n%l01d X* source lines\nXl01d accessed lines\n" 

"XlOld Xs total lines written\n", ConJoin.lines, ConJoin.f ile , 
access. lines , tgt.lines, tgt.f ile) ; 
if (size. stream * f open (size.f ile , V 1 )) 

{ f printf (size. stream, "Xld\nXld\nXld\nX . 3f \n" , ConJoin.lines, 

access. lines , tgt.lines, 

(double) access. lines / (double) tgt.lines) ; 
failure | « fclose (size. stream) ; 

> 

return failure; 

> 

The usual mainO command-line arguments arge and argv are passed di- 
rectly to initializationO, from which a mandatory ConJom_.f il® name, an 
optional target name, and an optional switch to disable the credits announce- 
ment are extracted. If a target is not named on the command line, a default 
name is made from the ConJoin.f ile by replacing the source file type with a 
default type (currently, .TeX). If no source file is named, or if the source and 
target files are the same, initializationO prints a usage message, then ter- 
minates the program with an exit value of TRUE. All error terminations return 
a nonzero value to the operating system in case Conjoin has been invoked from 
a script (or batch) file whose further processing may be affected. 

Both source and target files are opened; if this is not possible, the cause of 
the failure and the usage message appear, then On7oin terminates as above. If a 
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target file of that name already exists, it is renamed using an OLD_TYPE_DEFAULT 
(see default values in Section 7.3, above). 

A header is written by the timestampO function to the target file before 
any processing takes place. This banner stamps the file with the time and date 
it was created, and also records the target file name. The name of the source 
file is also written, along with an instruction not to edit the target file, but to 
make changes in the Corffoin source instead. (The reason for this is that editing 
the target file will not survive the next Coij7oin-ing of the same source file.) 

The main work of the program occurs in ConJoin.f ilesQ. This function 
reads lines from the source file and examines whether a Coiffoin directive ap- 
pears. If so, the action described in Section 3 occurs; if not, the line is copied 
to the target file intact. 

If an error occurs, either in Cotffo in-ing or closing files, the nonzero error 
value is set for termination, malloc-ated strings from the '/.path directive and 
elsewhere are freed (this may be done automatically by the operating system 
upon program termination, and could be redundant). This is followed by a 
terminating summary message and by saving the numbers of source, access, 
and target lines. 
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7.7 The initializationO Function 

♦**«.....**•••*•**•***•**♦•**••***•***•••****•* 

to id 

init iftlizat ion (urge , argr) 

/* Process coMaikd lino f il* aa»«s and option*, and rotrioTo 
sizs.fil* statistic*. 



STRIIG argr[ ] ; 

{ 

CHAR MgLHAI.LIIE]; 

STRIIG s; 

FILE osizs.strsam; 

comand.linoCargc , argr, nag); 
annonnesO ; 
if (**sg) 

{ usag«(); 

error_»essag«(CMD_LIIE_ERR, nsg, FALSE); 

•xit (TRUE) ; 

> 

file.dsf aultsO ; 

if (IOT st reap (Con Join.f ilo , tgt.filo)) 

{ strcpyGssg, ConJoia.f ils) ; 

*ConJoin_f ils ■ fUL; 
nsagoO ; 

•rror_asssag«(IO_SAHE_ERR, nag, FALSE); 

•xit (TRUE); 

strcpj(strchx(s * *trcpy(sizs_f ils , tgt.fils), 1 ■*). M .*iz”); 
if (sizs.streaa * fop«n(si2*.fil«, "r")) 

{ last.CJn.linss * FGETSIZE(nsg) ; 

last.acc .1 inss * FGETSIZE(nsg) ; 

Iast_tgt_lin«s m FGETSIZE(asg) ; 

1 as t. ns • .lines » FGETSIZE(«sg) ; 
fclos«(siz«.str«an) ; 

} 

} 

The initializationO function starts by passing the arge and argv pro- 
gram inputs to the command_line() processor, which proceeds through the 
argv strings looking for options and file names. Each unrecognized option is 
concatenated with any others and recorded in the msg string. (Caution: too 
many or long anomalous inputs may cause msg to exceed its allotted width, 
and may bomb the program in some implementations. If this appears to be a 
problem, future releases may adopt more robust handling of such conditions.) 
The first non-option string is assumed to be the ConJoin_iile, the second, the 
tgt_f ile, and any others are errors, appended to the msg string. 

Next, the program announce ()-ment is made. If credits has been set 
FALSE, the copyright, program, and version printout are inhibited. 

If a msg has been returned from initialization, a command-line error has 
occurred, usage () prints a short set of operational instructions, and the error 
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message follows. The function returns a TRUE value to the operating system. 

The * ile_def aultsQ function supplies a target file name and default file 
types if these were unspecified on the command line. If no tgt_lile has been 
named, the Conjoin.* ile name is used, with the file type changed to the target 
type default. If a tgt_f ile is named, but no “ ” appears in the file name, the 
default type is again appended. 

If the names of the Conjoin.* ile and the tgt.file are the same, the usage 
message and error are printed and the program again terminates with a returned 
value of TRUE. The ConJoin_*ile string is nulled so that no file line and column 
number appear in the error message. 

Finally, the function ends by constructing the name of the size_* ile, and 
then retrieving the last-time values of source, accessed, and target lines from it 
for use by the '/.size directive. 
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7.8 The command_line () Function 

/**«•♦•**••*****»**•*****•****************•••****************************/ 

▼oid 

ccwiaiid.linsCargc, argw, ug) 

/• Proce ss inf o rut Ion on the couand line: extract ConJoin_fil* 
and tgt.filo naaaee, and option -a, vhen present. Roturn with 
uk set to error conditiona. 

' 

STRUG argeC ], ug; 

{ i 

int i; 

STRUG •; 

eug * IUL ; 

for (i - 1; i < argc; i++) 

{ a - strlwr(argr[i]) ; 

if (*s IS OR •* IS VO 
{ switch (*♦+*) 

{ case ’a 1 : 

credits * FALSE; 
break; 
default : 

sprintf (ug + strlenCug) , "Unknown option: " 

"X* An", arge[i]>; 

> 

•arge[i] ■ IUL; 

) [ 

else if (ROT *ConJoin_f ile) I 

strcpy (Conjoin. f ile , s) ; 
else if (IOT *tgt_file) 

strcpy(tgt.f ile, s) ; 

else 

sprintf(ug * strlen(ug) , "Unknown com and: X*.\n", s) ; 

> 

if (IOT *ConJoin_f ile) 

street (ug, "Io source file nuedAn"); 

> i 

This function first NILs the names of source and target files and the return 
message, and then sequences through the command line arguments (excluding 
the Oth, which is the program path), one by one. Any argument beginning with j 

- or / is deemed an option, and only ~a is presently acceptable; its appearance i 

turns off the program, copyright notice, author, and version credits. Any other j 

attempted option input concatenates an Unknown option: string onto msg . 

The first command line argument not deemed an option is taken to be the 
ConJoin_f ile name, and the second, that of the tgt_ file. Any others append 
Unknown command: string to msg. 

The use of sprintf () to concatenate error strings is a simple way to produce 
the formatted msg involving the offense, the offending element, and a newline. = 

If no source file appears on the command line, this fact is appended to the 
error msg. = 

1 

. . — 

I 

I 
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7.9 The announce () Function 

If the credits switch is still intact (i.e., TRUE), then the copyright notice, author, 
program name, and version are printed; if not, these items are omitted. 


▼oid 


announce () /• Announce program, copyright, and author. 

•' 

{ 

int i; 

if (credits) 

{ for (i * 0; ecopyrightnotice [i] ; i-*+) 

printf ("Xs\n'\ copyrightnotice[i]) ; 
printf ("\n\t\t\t Conjoin PrograM" 

"\n\t\t\t %a\n\n", VERS I 01 ) ; 

> 

> 
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7.10 The error_message() Function 



to id 

•rror_mww»agw(n, », f) /* Writ* trror i«i«ag« n augmented with atriag s 

to atdout, indicating th« currant lino in thw 
source file. Repeat the Message on the target 
file if f is TRUE. 

/* — •/ 

STRUG a; 

{ * 

LOCAL STRIIG errasgC ] * 

{ "Beginning natch string not found; ”, 

"Break string ia invalid: ", 

"Coonand line error: ", 

"End-natch string not found: ", 

"Input and output files nay not be the sue: ", 

"Memory insufficient for queue.", 

"Io access file found: ", 

"lo lines copied from accessed file.", 

"Range separator missing.", 

"Size cowand case inwalid: " 


if (»ConJoin_f ile) 

printf ( H \aXa, %ld 1: %s%s\n". 

Conjoin .file , ConJoin.lines, arrmsgCn] , s) ; 

else 

printf ("Xs%s\n", errmsg[n], s) ; 

if Cf) 

fprintf (tgt.streu, "***ERR0R*** %s%s\n", errmsgCn], s) ; 


The LOCALized declaration of error messages accessed via globally defined 
macro indexes is admittedly fragile and prone to unreliability when later changes 
are made in the program’s error handling. It would have been more reliable to 
pass the error message directly, as a string argument, rather than as a numeric 
index. Each error message, in either case, appears only once in the program, 
so there is no storage advantage whether localized or dispersed. I tried it both 
ways. I think that the program is more readable with all the messages in one 
place. If, in future maintenance, this decision proves faulty, redistribution of 
error messages will be considered. 

The error_message() function merely prints the selected error message to 
stdout, and, if t has been set TRUE, also to the tgt_stream in slightly altered 
form. 
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7.11 The usage () Function 


void . 

Ma g € () /* Print a Boaaago on usaga ayntax of Conjoin. 


printf ("Uaaga: Conjoin <ConJoin sourca> <targat fila> 

" [<optiona>] \n\n" 

"\tSonrca fila typa default is . CJn\n M 
"\tTaxgat fila typa default is %a\n\n" 

M 0ptiona:\n" 

Do not announce the progran An' 1 , TCT.TYP E ^DEFAULT ) ; 


This function is invoked whenever an abortive usage error has occurred. The 
message reminds the user of the syntax that is required, the defaults that apply 
to that syntax, and the processing options that are available. It terminates with 
a TRUE value returned to the operating system. 
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7.12 The f ile_defaults() Function 


f il«. default a () /• Supply Conjoin fil« typo .CJn if ■isaing, «nd 

supply ■issiug parts of tgt.fila, if any. 


{ 

STRIIG s ; 

if (I0T <s * strchr (ConJoin.f ils , > .*))) 
strcat (ConJoin.f ils , M .CJn M ); 
if (IQT stgt.f ils) 

{ strtcpy(tgt_fils, ConJoin.f ils, 

strchr(ConJoin - f ils, * . *) - ConJoin.f ils) ; 

} 

if (10T (s * strchr(tgt_f il« , *.’))) 

strcat Ctjt-f ils , TGT.TYPE.DEF1ULT) ; 

> ''77 77 ^: 777 :' " 7 " " ‘717777 

Note that the ConJoin_f ile will always have a file type; if one is not pro- 
vided by user input, it is supplied in the first if clause. If no tgt_file has been 
named, the ConJoin_f ile name is used, up to the (a “ is guaranteed to 
appear by the first step above). The length of text copied excludes copying of 
the dot. 

If the tgt_f ile bears no the TGT_TYPE_DEFAULT is applied. Thus, the 
target file also always has an explicit file type. 
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7.13 The open_io_f iles () Function 




void 

op#n.io.f il«s () /* Op«n ConJoin.filt ind tgt.filt into ConJoin.strwui 

and tgt.strwu. R«naa« old tgt.filw, if any, 
with OLD. TYPE. DEFAULT. Twmiaatw with an wrror 
■ess ago via filo.optnO if filws cannot b# opwnwd. 



{ 

CHAR tgt .bah [FILE! AKE.HAI] ; 

FILE ♦ f ; 

STRUG a ; 


Con Join.str warn * f il«.opwn(ConJoin.f ilw , "r ") ; 
if (f * f open(tgt_f ilw , "r")) 

{ fclose(f); 

a * strchr(strcpy(tgt.bak, tgt.f ilw) , * .0; 
strcpy (a , OLD. TYPE. DEFAULT) ; 
remove (tgt.bak) ; 
rename (tgt.f ile , tgt.bak) ; 

> 

tgt. stream » f ile. open (tgt.f ilw, "w"); 

} 


The first fopen() finds the Coi^oin source file for reading. If the file cannot 
be found, or otherwise cannot be opened, the program terminates at this point 
with an error message and a TRUE value returned to the operating system. 

The if clause checks to see whether the file named by tgt_f ile currently 
exists by opening the file for reading. If it does, a backup file name is created 
using the name up to the followed by the OLD_FILE_TYPE. Then the current 
file is renamed to this tgt_bak. 

The final fopen() opens the target file for writing, with the same termination 
consequences as above if the target cannot be opened. 
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7.14 The file_open() Function 

This function is equivalent to fopen(), except that if the file cannot be opened, 
an error message is printed with the reason followed by program termination. 
The function is only invoked where abortive action is desired in response to an 
error. The name is nulled prior to calling errorless age to suppress the file 
name and location portions of the printout. 

MU 

FILE * 

f ile_open(nase, use) 

/* Open the name file for given use , and return resulting stress. 

If file cannot b« opened, print reason, and abort processing. 


STRIVG name, use; 

{ 

CHAR s [KAX_LIIE] ; 

FILE * stream; 

if (IOT (stress * f open (name, use))) 

{ strcpjCs, nane); 

♦name * IUL ; 

s truest (street (s , "), strerror(errno) , XAI_LIIE “ 1); 

err or _ss ss age (CHD .LIVE JERJl, s, FALSE); 
exit (TRUE); 

} 

return stress; 


in in 
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7.15 The timestampO Function 

The purpose of the timestampO function is to annotate the target file being 
written with informative and warning commentary. The information consists of 
the target file name (tgt Jfile), the current time (accessed via ANSI standard 
functions time() and localtimeO), and the name of the ConJoin_file that 
created it. The warning is simply an exhortation not to revise the file. Nothing 
dire happens if this file is altered, but the user probably meant for the changes 
to have been made in the original source file. When Coij/oin-ed again, changes 
in the target file will be lost. 




▼oid 

timestampO /* Write the tgt. file name and a t ime -stamped header with 

a revision warning onto the tgt.stream. 

/♦ */ 

{ 

time.t clock; 

CHAR a tine [26] , 

bar [KAX.LIIE] , 
blanks [MAI.LI1E] ; 

STRUG sp, text; 

struct tm * t ; 

int n; 


n * strlen(open) ♦ strlen(close) ; 
strnset (bar, , « , l PAGE.VIDTH - n) ; 
strnset (blanks, » >, PAGE.VIDTH - n - 2) ; 
t ime(Aclock) ; 
t 3 localtime (tclock) ; 
stratrim(strcpy(atime , asctime(t))) ; 
sp 3 right.f ill (at ime , strlen(tgt.file) + n + 5) ; 
fprintf (tgt. stream, M %a (Xs)Xs(Xs)Xs\n'* , open, at ime, sp, 
tgt.file, close); 

fprintf (tgt .st ream, "XsXsXs\n", open, bar, close); 

text 3 ”%s| This file was ConJoin-ed from input file Xs.Xs|Xs\n M ; 

sp 3 right.f ill(text , strlen(ConJoin.f ile) - n - 7) ; 

fprintf (tgt. st ream, text, open, ConJoin.f ile , sp, close); 

fprintf (tgt .stream, M Xs IXslXs\n", open, blanks, close); 

text 3 "Xsl DO VOT REVISE THIS FILE .%s IXs\n n ; 

fprintf (tgt. stream, text, open, right.f ill (text , n - 7) , close); 

fprintf (tgt .stream, "Xs |XslXs\n M , open, blanks, close); 

text 3 "Xs| To make revisions, modify the original f ile .XslXs\n M ; 

fprintf (tgt. st ream, text, open, right.f ill (text , n - 7) , close); 

fprintf (tgt. st ream, "XsXsXsNn", open, bar, close); 

tgt .lines ♦* 8; 

} 


The only tricky part of this function is in correctly creating the flush-right 
time-stamp box. The function strnset () from TOP-C creates bars for the 
top and bottom of the box, while right_f illO provides the correct number of 
blanks for formatting. Even though the global variable spaces is not referenced 
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within timestampO, it is changed as a side-effect of right ill 0 (see the 
discussion in Section 7 . 16 , below). 

The reason for using stratrimO before copying asctimeO to atime is that 
the string returned by asctimeO is terminated in a newline character, and it 
is necessary to remove the trailing white space for proper formatting. 

The tgt_lines variable is finally augmented by the number of lines written 
onto the target file by this function. 

As an example, the header written by timestampO on the target file com- 
prising the body of this report is 

X (Fri Jul 31 11:20:39 1992) (c j-body .Tel) 

sssssasax **««*■»» ****-=*****■■*■****«■ *■■*** “***■**■ mmmmmmmmwxxummmmMwmmmmm 

XI This file was ConJoin-ed fro* input file cj.body.CJn. I 

XJ 1 

X| DO I0T REVISE THIS FILE. I 

XI I 

XI To safe* revisions, modify the original file. I 

* 
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7.16 The right _f ill O Function 


right.filK*, n) /• G«n«r»t» spaces as a blank string of langth 

P1GE.WIDTH - n. Return spaces. 


STRIIG s; 

return strnset (spaces, 1 P1GE.WIDTH “ strlen(s) - n) , 

> 

This simple function perhaps exemplifies the practice of undue parsimony in 
programming: the use of an existing, idle global data structure by a function it 
was not initially intended to serve. Throughout the remainder of the program, 
spaces carries the indentation prefix for lines copied from accessed files. But 
here, before the scanning of the source even begins, it is free for other duty. 
Luckily, its name fits both usages. This general practice can lead to very fragile 
and hard-to-read code if overdone. Even though this module is only invoked 
from a single function of the program, and even though it is very tiny, the 
program modularity is less than optimum. 

This function should be noted as a possible target for later perfective main- 

tenance. 
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7.17 The ConJoin_files() Function 

This function processes the Conjoin source file to produce the target file via the 
directives described earlier, in Section 3. The algorithm is straightforward. 


ConJoin_fil«*() /• Proc#»» th* ConJoi Xk lourc* file and cr«at« th* 

expanded target file . Re turn a nonzero value 
if an error occura, or a 0 value if none. Count 
ConJoin_lines , access.linea , and tgt. lines . 


{ 

BOOL error; 

CHAR hold[HAI.LIIE] f 

line [MAI .LIRE] ; 
STRUG extract; 


> 


error * FALSE; 

espaces * IUL; 

for (Con Jo in-line a « 0; fgetaCline, HAI.LIIE, ConJoin.strean) ; ) 
{ ConJoin_lines++; 

tgt^linea +♦; 
if (I0T eatrfnb(line)) 

{ fprintf (tgt.streu, line); 

continue ; 

> 

if (stretrCline, open)) 

{ if (extract * st rat r (line, ACCESS.SIGIIL)) 

ntrepy (hold, line); 
error I* direct ive( extract , line); 

> 

else 

extract * IIL; 

fprintf (tgt.streaa, "%a", line); 
if (extract) 

error I* accessOiold «■ (extract * line) + 
•trlen(ACCESS_SIGIAL) ) ; 


> 


return error; 


The error switch is set FALSE and spaces is HUL-led in preparation for 
processing. The loop iteratively reads in a string line until an end-of-file or 
reading error occurs. Each line read in augments the number of ConJoin_lines 
and tgt_lines. All source lines copy into the target file in one form or another. 
If a line is blank, it is immediately written to the target file, and processing 
continues. 

Each line is prescanned to see if it contains a CoTffoiu directive, as indicated 
by the appearance of a comment opener. If one exists, then the line is checked 
for the appearance of an ACCESSES I GHAL, whose location is saved in the variable 
extract. If line is recognized as an '/.access it is saved in the hold buffer. 
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Thereafter, the line is processed as a possible directive. A non-IIL extract 
value sent to directive () is a signal that the directive is an ^access and is 
only to be prepared for showing, if the show mode is in effect. The remainder 
of the processing of an '/.access directive takes place after the line has been 
written on the target. 

If no comment opener was detected, extract is set to MIL so no access () 
action takes place later. 

The line either prints as it was when read in, or as altered by directive(). 
Only '/.size and '/.show directives cause alterations to the line; '/.size inserts a 
numeric value into the line, and Kshow surrounds the line with preverbatim 
and postverbatim target processor commands when turned on. 

If extract is non-NIL, the hold line is processed as an '/.access directive 
(the line will have been corrupted in the show mode). The position after 
the '/.access signal in hold is computed from its location in the line prior to 
directive () processing. 

Processing '/.access directives is delayed with respect to processing of other 
directives so that transcribing the extracted text can follow the copying of the 
directive itself onto the target file. 

On completion of scanning the source file, the function returns the compound 
results of error detection. 
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7.18 The directiveO Function 

Because of its length, this function will be described in increments. Overall, the 
structure is comprised of three communicating parts: 

• declaration and initialization 

• directive action 

• preparation for showing 

The first action is to preserve the incoming text by copying it into the line 
string, which is processed instead. However, text will also be processed if it 
contains a %size directive or if the show condition is TRUE. The text string is 
later written onto the target file by the invoking function. 


BOOL 

diractivaCaxtract , taxt) 

/* Process Conjoin direct I tsb that may appear in the text string. 

If extract is non-IIL, the text contains an access direct ire 
that nay only need to be prepared for shou-ing. In case of 
Xsize, erite the appropriate values into text. Insert 
pravarbatin and postverbatin into text if show is, or has just 
turned, TRUE. Return TRUE if a bad Xsixe case appears; FALSE 
otharvisa . 



STRUG extract, text; 

{ 

STRIIG s, 
t; 

CHAR g, 

line [HAX _LI IE] ; 

BOOL change.shov; 

strcpyClina, text); 

The next, and largest, segment of the function is a 12-way if... else il 
else ii . . . directive-selection structure. If extract is non-HIL, a delayed 
'/Jaccess directive is in effect, so no action takes place in this step. The t pointer 
is set to the location of the beginning of the directive in the line. 

if (axtract) 

t ■ lina + (axtract ~ taxt) ; 

Many of the other directive actions simply record parameter values: 

alsa if (t * strstrClina, BREAI_SIGIAL)) 

straxt (mark, t + strlan(BREAI_SIGIAL)) ; 

alsa if (t * strstrClina, COUIT.SIGIAL) ) 

straxt (count signal, t + strlan(COUIT_SIGIAL)) ; 
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else if (t * strstr (line , POSTFIX. SIGIAL)) 

strext (postfix, t + strlen(POSTFII.SIGIAL) ) ; 
else if (t * strstr(line , PREFIX.SIGIAL)) 

strext (prof ix, t + strlen( PREFIX.SIGIAL)) ; 
else if (t * stratrdine, RAIGE.SIGIAL)) 

strext (rang* , t ♦ strlen(RAlGE.SIGIAL)) ; 


else if 

{ 

> 


(t - strstr (lino, GARBAGE. SIGIAL) ) 
if (g * *strfnb(t ♦ strlen(GARBAGE.SIGIAL) ) ) 
garbage - g; 


also if (t * strstr dine , TAB. SIGIAL)) 

tabwidth * atoi(t + strlen (TAB. SIGIAL) ) ; 


In each of these, the remainder of the directive after the detected SIGNAL de- 
termines the new value of the parameter (white space suppressed). The param- 
eters affected are mark, countsignal, garbage, prefix, postfix, range, and 
tabwidth. 

A similar action takes place with path_list items, except each path ex- 
tracted from the directive is saved in malloc-ated memory by strdupO of 
Section 8.2. 


«ls« if (t * strstr (lins , PATH. SIGIAL)) 

{ path.list [path.list. size++] * 

strdup(strext (t , t ♦ atrlen(PATH.SIGIAL))) ; 

} 


If a ’/.column directive appears with a positive value, the spaces string is 
filled with an equal number of blank characters; otherwise spaces is nulled. 


else if (t » strstr (line, COLUHI.SIOIAL)) 

{ column * atoi(t ♦ strlen(COLUHI.SIGIAL) ) ; 

if (column > 0) 

{ strnset (spaces , 1 * , column); 

column * 0; 

} 

else 


} 


♦spaces * KUL; 


A - /,show directive line is examined for on or off alternatives. 

else if (t * strstr (line, SHOV.SIGIAL)) 

{ b * strlwr (stratr im(t + strlen(SHOW.SIGIAL) )) ; 

if (I0T strcmp(a, "on")) 

change. show * TRUE + TRUE; 
else if (*0T strcmpCs, "off")) 

change .show = TRUE + FALSE ; 
if (change. show AID I0T show) 

show * change. show - TRUE; 

> 
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Either on or o ff causes change_show to switch from 0 (FALSE) to 1 (TRUE + 
FALSE) if show goes off, or to 2 (TRUE + TRUE) if show goes on. Unrecognized 
show alternatives are ignored. If '/.show has called for action (change_show has 
been set to a nonzero value), and if show is currently off, then whatever action 
was called for takes place immediately, in case the directive was to go on. 

The remaining directive, '/.size, causes the action 

else if (t ■ strstr (lin« , SIZE.SIGIAL) ) 

{ do 

{ *t - IUL ; 

•s itch (*(t ■ strfnbCt + strlsu(SIZE.SIGIAL) ) )) 

{ cass ’c 1 : 
case 'C*: 

s * last.CJn.linss; 
break; 
case *a J : 
case »i»: 

s * last_acc_lines; 
break; 
case , t j : 
case 

s * last .use. lines; 
break; 
case ’t’: 
case *1* : 

s * last _tgt .lines; 
break; 
default : 

s - "O' 1 ; 

•rr or _M ssago ( S IZE.EUt , tort. FALSE); 
return TRUE; 

> 

spriutf (text , "%s%s*s”, line, s, ++t) ; 

} ehile (t * strstr (strcpyCline , text), SIZE.SIGIAL)) ; 

> 

Nulling the character where the SIZE_SIG1TAL was found truncates the line at 
that point, removing the ’/.size directive. The character after the SIZE_SIGMAL 
causes the corresponding number of lines saved in the size history file to replace 
the */,size directive in the reconstructed text by sprint! (). The do loop 
iterates until no further ’/.size directive is detected on the line. 

The final segment of the directiveO function prepares the line for possible 
explicit display in the target document. It does this by inserting pre- and post- 
verbalim environment commands around the directive. String t will be non-HIL 
if a directive was detected. 

if (t AID shoo) 

{ str insert (text + (t - line) , preverbat i*) ; 

if <*close AID (t ■ strstr(text , close))) 
strinsert (text , postverbat im) ; 


else 


mi in mu in i i li i ii iiiiiiiiuj i b i , iiiiliilii! 
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■treat (stratri»(t*xt) , po»t**rbatim) ; 
if (change.ahos) 

show ■ change. ahov * TRUE; 

> 

return FALSE; 

> 

If no directive was found in text, the function terminates with no action 
taken. 
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7.19 The strextO Function 

The purpose of this function is to extract the substring up to the closing com- 
ment mark (if any) and copy it into another, trimmed of leading and trailing 
white space. 


/*•♦******************•*♦*****♦***********♦*********************♦♦*••••**/ 

STRUG 

strext (s , t) /• Extract string t up to the close-coainent string, if closs 

is not null, or to ths end of t if null, into s. Remove 
loading and trailing blanks from s and return s. 

/• — */ 

STRUG s, t; 

{ 


STRIIG p; 

if (*close AID (p * strstr(t , close))) 
strtcpy(s, t, p • t); 

also 

strcpy(s, t); 
return stratrim(s) ; 

> 


ii« ID .Hi 1 1. i li li II I I III ill luMililiii liiui iiMUMMiliillilJlII. , I, I II I, j i I J |||,| | | ||, 1 1 , 
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7.20 The accessO Function 


BOOL 

access (buffer) 


/* 

STRUG 


/• Process the text extraction operation specified 
in the line buffer to the tgt.stream. Return 
FALSE if no error, TRUE if an error occurred. 
- •/ 


buffer; 


STRUG 

bgn .match [MAI.COITEXT ♦ 1] , 
end .match [HAX.COITEXT + 1] ; 

CHAR 

module [FILEVAJfE.HAI] ; 

BOOL 

error; 

FILE * 

modulestream; 

int 

bgncount , 
bgnoffset , 
endcount , 
endoffset , 


strext (buff er , buffer); 

if (match. parameters (buff er , module, bgn.match, end_match, Abgncount, 
ftbgnoff set , tendcount , Aendoffset)) 
return TRUE; 

if (I0T (modulestream * open.access (module))) 

{ error_message(IO_ACCESS_ERR, module, FALSE); 

return TRUE; 

> 

printf ("Xsaccess %sXs\n", open, buffer, close); 
if (eprefix) 

fprintf (tgt.stream, "%s\n M , prefix); 
error * scan. to_bgn_match (modulestream, bgn.match, bgncount, 
bgnoffset); 

error I* copy. t o. end j»atch (modulestream, end .mat ch , endcount, 
endoffset) ; 

for (i * 0; bgn.match [i] ; i++) 
f ree (bgn.mat ch [i] ) ; 
for (i * 0; end.match[i] ; i++) 
f ree (end. match [i] ) ; 
error I* f close (modulestream) ; 
if (epostfix) 

fprintf (tgt.stream, "%s\n M , postfix); 
return error; 


The first step of the algorithm removes the trailing comment signal and 
leading and trailing white space from buffer. The second step extracts the 
name of the file to access and the search parameters; if no error is encountered, 
the algorithm proceeds. 

The third step opens the module stream; if the extracted file name is not 
found in the current directory, each of the directories named in %path directives 
is searched. If the file is found and opened successfully, the next step lists 
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the name and extracted parameters by using current settings of the '/.access 
separator strings. 

Next begins the actual access: If there is a prefix, it is written into the tar- 
get file. The access file is searched for the beginning match conditions described 
in Section 3.2, and thence copies until the ending match conditions have been 
met. Finally, the access file is closed, the postfix is written to the target file, 
and the function terminates, returning the indicator of any error condition that 
may have occurred. 

Note: the error expression contained in the three statements near the end of 
the function should not be combined into a single statement because the order 
of evaluation of functions is unspecified in the ANSI standard. 


Ill III Mi li 11: Mil Ulii i 
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7.21 The match_parameters() Function 



BOOL 

m*t ch.pax&M«t«rs (buffer , Module , bgn .match, end_m*tch, bgneouat, bgnoffset, 
•ndcount, endoffset) 

/• Extract access Module name , and beginning and ending access 
conditions. Return TRUE if an error is encountered, FALSE 
otherwise. 

/* */ 

STRUG buffer, bgn_m&tch[ ], end_match[ ], Module; 
int ♦bgneount , ♦bgnoffeet, ♦end count, ♦endoffset; 

{ 

CHAR liue[HAI.LIIE] ; 

STRUG s , 
ti 

if (HOT (s * atrstr (strepy (line , buffer), Mark))) 

{ error .Message (BREAK. ERR, buffer, FALSE); 

return TRUE; 

} 

st rat rim( st rtepy (module , line, s - line)); 
if (I0T (*(t * strfnb(s + strlen(nark))) 

AID (s * strstr(t, range)))) 

{ error _mes sage (RAIGE_ERR , buffer, FALSE); 

return TRUE; 

} 

*8 * IUL ; 

s +* strlen(range) ; 

if (access. condition(t , bgn.Match, bgneount, bgnoff set , 1)) 
return TRUE; 

if (access.condition(s , end.match, endcount, endoffset, -1)) 
return TRUE; 

return FALSE; 

} 


The first steps above extract the name of the file to access into module by 
locating the ’/.break mark (signaling error if none is found) and copying that 
portion of the input buffer. 

The next segment sets t to the starting-match condition, beginning just 
past the mark location and extending up to the range marker. (If no marker is 
present, the function terminates returning an error indication.) Putting IUL in 
place of the marker isolates the starting match specification string. 

Note that string s has been positioned just past the range marker, and 
therefore points to the end-condition string. The access_condition() function 
invocations extract the context strings, context count, and offset values for the 
matches to be made in scanning for the beginning match and copying to the 
ending match. 
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7.22 The access_condition() Function 

Access match conditions are extracted from the string buffer parameter. The 
context strings are copied into the natch dynamic string array, but count and 
offset values are first set by locating these terms and removing them from 
the buffer. Removal merely requires seeking for countsignal, +, and then 
converting substrings to integer values, and finally inserting HULs to isolate the 
match-string portion of the condition. 


BOOL 

access. condit ionCbuff er , »atch, count, offset, init) 

/* Extract access condition fro* buffer. Set offset to init if 
no offset is parsed in the buffer. Return TRUE if an error 
is encountered, FALSE otherwise. 


STRIIG buffer, natch [ ]; 
int •count, *offset; 

{ 

int n; 

STRIIG s, t; 

•offset * init; 

•count M 1 ; 

s * stratrim(buffer) ; 

if (t * strstrCs, countsignal)) 

{ «count * atoiCs * t + strlen (count signal)) ; 

•t - IUL; 

if c Ct * strchrCs, >+’)) OR (t * strchr(s, *-•))) 

{ *off set * atoi(t); 

*t * IUL; 

} 

else if (isdigit (^buffer)) 

{ *offset * atoiCbuff er) ; 

•buffer * IUL; 

> 

s * buffer; 

for (n * 0; *s AID n < HAI.COITEIT; n++) 

{ if (t * strstrCs , mark)) 

{ *t ■ IUL; 

t +* strlen (mark) ; 

} 

match[n] = strdup(strtrimCs)) ; 
s * strfnbCt AID *t ? t : s ♦ strlen(s)); 

> 

if (n > 0 AID match [n - 1] IS IIL) 
return TRUE; 

match [n] * IIL; 
return FALSE; 

> 
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7.23 The open_access() Function 

The open_accessQ function attempts to open the file named as the param- 
eter. Failing this, it attempts opening this file in each of the directories previ- 
ously named in # /,path directives, until successful. Then, the open file stream 
is returned. If unsuccessful, a MIL value is returned to the calling procedure, 
accessO, of Section 7.20. 


FILE • 

op«n_acc#ia (f ile) /* Open the specified file for reading. 

/• — */ 

STRUG file; 

{ 


int i; 

CHiR path [FILEIIME.MAI] ; 

FILE * stream; 

strcpy (path , f il« ) ; 

for (i ■ 0; I0T (stream * fopenCpath, "r")) AID i < path.list.size ; i++) 
strcat (strcpyCpath, path.list [i]) , f ile) ; 
return stream; 

} 


80 


92-12 


7.24 The scan_to_bgn_matchO Function 


/*«****4 

scan.to. 


/* 

FILE * 
STRIIG 
int 
{ 


BOOL 

.bgn_match(modulestream, bgn.match, bgncount. bgnoffset) 

/* Scan the modulestream for the beginning match condition and 
return positioned to access the first line to be copied. 

modules t ream; 
bgn_match[ ] \- 
bgnconnt , bgnoffset ; 


-*/ 


fpos.t 

int 


BOOL 

long 

CHAR 


fpqnene [KAZ.Q] ; 
n, 

offset , 
qex; 
error ; 
qe; 

text [HAX.LIIE] ; 


n * error ■ offset * 0; 
qe * "1 ; 

while (I0T fgetpos (modulestream, tfp) AID 
fgetsCtext , HAX.LIIE, module stream)) 

{ qex * (int)(++qe HOD MAX.Q) ; 

fpqueueCqex] * f p ; 
if (bgn_match[n] ) 

{ if CIOT strstr (text , bgn_match[n] ) ) 

continue; 


if (bgn_match[++n]) 
continue; 

if (--bgncount <* 0) 

{ if (bgnoffset <■ 0) 

{ qex * ( int ) ( (qe + bgnoffset) HOD HAX.Q) ; 

fsetpos (module stream, tfpqueueCqex] ) ; 
break; 

} 

else if (bgnoffset-- IS 1) 
break; 

> 

else 

n * 0; 

> 

else if (I0T bgnoffset) 

{ fsetpos (modulestream, tfpqueue [qex] ) ; 

break; 

> 

else if (-M-offset >* bgnoffset) 
break; 

> 

if (bgn.match [0] AID bgn. match [n] ) 

{ error. .■•»»age(BGI.IUTCB.EWl. bgn_»atch[n] , TRUE); 
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•rror ■ TRUE; 

> 

return error; 


In this algorithm, qb and qe are the queue-beginning and queue-ending in- 
dices of lines read from the access file. If the beginning offset is negative, then 
when the beginning match and count conditions are reached, the beginning line 
is located from the queue. The lines themselves are not queued, but rather their 
positions in the file are stored in a file-position-queue, fpqueueC ]. Since the 
queue length is limited to MAX.Q elements, it is necessary to treat the queue 
circularly, indexed by integers qbx and qex. 

Until the beginning access condition is met, the file positions and text lines 
are read into Ip and text, respectively. The position is saved in Ipqueuefqex] , 
while text is examined for beginning match conditions. 

One will note that the copy_to_end_match() function (Section 7.25) main- 
tains a text queue, rather than a file position queue. That alternative was also 
considered here to make the two functions more similar. The speed trade-off 
between the two alternatives — i.e., constantly allocating, copying, and freeing 
strings into and from the queue vs. the one-time repositioning of the file- 
seemed moot. The use of the text queue, however, required that the copying 
function also needed access to the queue. Manipulation of the queue in copy- 
ing seemed less straightforward and much different from this scanning function. 
Simplicity and similarity finally won out. 

As long as the bgn_match[n] string is non-null, there is a match to be found; 
otherwise, the string matching condition is considered satisfied. Whenever a 
match is satisfied, its count is decremented, and the next occurrence of the 
bgn_match array is sought (at n = 0). 

Upon reaching the context and count conditions, if the beginning offset was 
zero or negative, the queued location of the line read bgnoffset lines earlier 
is used to reposition the input file to next read at the specified line. The loop 
breaks at this point and the function terminates. 

If the beginning offset value is positive, then bgnoffset is decremented to 
count (and thereby skip) the line. If the offset (before the decrement) is one, 
then the loop breaks and the function terminates, as the end matching condition 
has been fulfilled. 

If the function began without a context to be matched and no offset, then 
the file is reset to the beginning, and the function terminates. If there was a 
beginning offset only, an offset variable counts up until the specified offset is 
reached before the loop is broken. 

If, after the loop terminates, if bgn_match[0] and bgn_match[n] both are 
un-nulled, this is an indication that a match was to be found, but was not. An 
error message results in this case. 
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7*25 The copy_to_end_match() Function 

The copy_to_end_match() function is again long enough that a segmented 
presentation of its operation is warranted. The algorithm is similar to the 
scan_to_bgn_match() function earlier described (Section 7.24), except that 
copying replaces scanning. The function and data declarations are 


BOOL : : ~ - ■ ■■■ r^v: =*:. ... 

copy_to.*nd^match(*odttl«*tr*», •md L—tch , •ndco nnt , ♦ndoffs«t > 

/• Copy lino# from »odnl*str«aji to tgt_wtrwa», op until tho •nd-Mtcfc 
condition. is satisfiod. Ratora TRUE if an orror was ancountarad, 
printing tha appropriata arror aassaga; ratozn FALSE otharwisa. 


FILE **odulastraa»; 

STRUG and.»atch[ ]; 

int andconnt , andoff sat ; 

i 

int count , 

arror , 
off aat , 
n, 

qbx , 
qax; 

long qb , 

q«; 

CHAR taxt [MAI .LIRE] ; 

STRIIG txquaua[HAX_Q] ; 

The variables qb, qe, qbx, qex, and error operate as they did earlier; count 
is there to measure whether any copying actually takes place. Unlike the ear- 
lier function, which maintained a file position queue, this function maintains 
a real text queue, txqueueC ], because excessive disk thrashing would re- 
sult if a file-position queue approach function w ere taken, as was done in the 
s can_t o_bgn_mat ch ( ) function described earlier (Section 7.24). _ . 

The function is otherwise very similar in structure to the scan function. The 
end of the queue is initialized to -1 because qe is incremented before it is used; 
therefore the first element read will be inserted into queue slot 0. A loop gets 
(and counts), queues, and copies text strings from the modulestream. When 
an end matching context has been specified on entry, end_match[n] will be MIL 
at the exit from the loop if the condition has been fulfilled. Hence, a non-MIL 
match string signals an error condition. Similarly, a zero count means nothing 
was copied — another error condition. 

qt ■ -1 ; 

n * 0; 

for (count * orror - offoot - 0; fgot*tr(t«xt , ■odulastreaa) ; count-*-*-) 

{ if (ondoffsot <■ 0) 


i lil Hill I I niilittiyWiliiNiiii 
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> 

if («nd_*atch [0] AID «nd_match [n] ) 

{ err or ssaga ( EVD.HATCH.ERE , end_m*tch[n] , TRUE); 

error * TRUE; 

> 

if (IOT count) 

{ err or .message (10. COPY. ERR , TRUE); 

error * TRUE; 

> 

return error; 


There are several if-clauses inside the loop above. The first is exercised 
when there is a negative endoffset 

{ if (endoffset <* 0) 

{ qex - (int) (++qe MOD MAX.Q) ; 

if (IOT (txqueue [qex] « atrdup(text)) ) 

{ error.message (MEMORY. ERR , , "' I FALSE); 

error * TRUE; 
break; 

> 

if ((qb * qe ♦ endoffset) >*0) 

{ qbx - (int) (qb MOD MAX.Q) ; 

free (putline (txqueue [qbx] ) ) ; 
txqueue [qbx] ■ IIL; 

} 

if (end_match[n]) 

{ if (IOT strstr(text, end_match[n] ) ) 

continue; 

if (end_»atch[++n]) 
continue; 

if ( — endcount <* 0) 

{ ehile (qb <* qe) 

{ qbx ■ (int) (qb++ MOD MAX.Q) ; 

free (txqueue [qbx]) ; 

} 

break; 

> 

else 

n * 0; 

> 

> 

A zero or negative endoffset causes the text to be inserted into the next queue 
slot (if there is no memory error). If the queue has reached a length such that 
the line at the beginning of the queue is ready to be transferred into the target 
file, it is copied via putline () (Section 7.27), its memory allocation is freed, 
and its former queue element set to MIL. 

If an end_match[n] context exists and appears within the text string, the 
next end_match [++n] context match is sought. When all individual end matches 
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have been made, endcount is decremented and the next series of context matches 
are begun. When the count reaches zero, any enqueued text is freed, and the 
loop terminates. 

The remaining if -clauses inside the loop operate when endoffset is posi- 
tive: 

•ls« if (•nd_»atch[n]) 

{ put line (text) ; 

if (VOT strstr(t«xt, •nd_match[n] )) 
continue ; 

if ( «nd_B«t ch ) 

cont inue ; 

if ( — endcount > 0> 
n « 0; 

> 

else if (offset-M- < endoffset) 
put line (text ) ; 

else 

break; 

In the first of these clauses, if there is an unsatisfied ending string match, then 
the text is put to the target file and the line is checked for a string match. If 
there is a match, and if further matches are pending, the process continues. 
Otherwise, the end count is decremented. If there are still more contexts to 
match, n is reset to 0, and the next context is sought. When endcount reaches 
zero, the end-matching context is fulfilled. 

Once the end string match condition has been satisfied, the offset is checked; 
if that part of the end condition is unfulfilled, the text copies into the target 
file and is counted in offset. Finally, on reaching the goal endoffset, the end 
condition is satisfied, and the loop terminates. 
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7.26 The fgetstrC) Function 

The purpose of the fgetstrO function is to obtain a string from a named 
stream, replace tab characters in that string with spaces, and pass that string 
back to the calling function, copy_to_end_match() (Section 7.25). In addition, 
fgetstrO removes trailing white space and replaces the ending newline. 

An entire line at a time is fetched from the stream, unless an end-of-file or 
anomalous condition has been reached. As each character of the input stream is 
scanned two checks are made: If a scanned character is a tab (i.e., \t ), a span 
of spaces is inserted to align the next character on a multiple of the tab_width. 
If a scanned character is not a space or other printable character, the garbage 
character is substituted in its place. Otherwise, the character is written into 
the parameter string intact. 


striig 

fgetstr(s , straw) /• Gat string s from the naMd straw with 

TABs raplacad by spaces, and return it. 


STRIVG s ; 

FILE * stream; 

{ 

CHAR c , 

p[HAIJLIIE] ; 
int i, 

j; 

STRIIG q, 

t; 

if (I0T (q * fgetsCp, HAXJ.IIE, stream))) 
return IIL; 

for (t ■ s, i * 0; c * aq++; ) 

{ if (c IS >\t>) 

{ j * tabwidth - (i MOD tabwidth) ; 

while (j — ) 

{ *t++ ■ J * ; 

♦+i; 

> 

cont inne; 

> 

else if (I0T (isspaca(c) OR isprint(c))) 
c * garbage ; 

♦t++ * c; 
i++; 

> 

at ■ IUL ; 

return strcat (strtrim(s) , "\n"); 

> 
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7.27 The putlineO Function 

The putlineO function writes its string argument, column-adjusted in accord 
with the last ‘/.column directive, to its stream argument, provided that the string 
is not null and contains a newline. Null lines and lines not terminated in newline 
are both considered anomalous. 


STRUG 

putlina(a) /* Write the the string s onto the output stream, properly 

col ous ted. The string is presumed to exist and contain 
a. navlina . Count th« output both as om of th« 
access. lines and tgt.linss. 

.... — ~ ./ 

STRIVG a; 

{ 

STRIVG t; 

if (• AVD (t * strchrCs, ’Xn'))) 

{ t * s + (column < 0 ? min(-column, t - s) : 0) ; 

fprintfCtgt .stream, M X»Xs", spaces, t) ; 
access. line#++ ; 
tgt_lines++ ; 

> 

return s; 

> 


The local string variable t locates the newline, so t - s is the string length, 
not counting the newline. If the column level is negative, the input string is to 
be left-truncated by -column characters (the spaces string in this case will have 
length 0, set in response to the ‘/.column directive). This is done by starting the 
actual printing at the proper offset later in s. In order that the s not be accessed 
beyond the end point, the lesser of the two length alternatives is assigned to 
t. If column is zero or positive, spaces has been set to this length either by 
default or by a %column directive; t is set to s in this case. 

The writing of t preceded by spaces thus achieves the desired formatting: 
For negative column values, spaces is null, and if column is zero or positive, 
spaces has this width. 

The access_lines and tgt .lines values are augmented to count the line 
written both as one emanating from the access source as well as one written to 
the target file. 
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8 TOP-C LIBRARY FUNCTIONS 

Several calls to functions in my personal library appear in the Coifjo in program. 
Listings of these appear in this section for informational and completeness pur- 
poses only. None of these falls under the jurisdiction of the JPL copyright notice 
placed on the source files or the copyright notice printed in this report. 

These files all access appropriate # include files to assure that each ANSI 
and TOP-C function reference conforms with its prototype declaration. 

8.1 The stratrimO Function 

The stratrimO function was patterned after the atrim function of Clipper: it 
removes all leading and trailing white space of a given string and returns the 
result. 




STRIIG 

stratrimCs) /* Trim all white space from s, loading and trailing, and 

than return s. 

/• */ 

STRIIG s ; 

{ 


FAST STRIIG p; 

p ■ strfnb(s) ; 
strtcpyCs, p, strlen(p)); 
return strtrim(s) ; 

> 

First, p advances to the first nonblank character of s; then memmoveO copies 
p into s, which left-justifies s. Finally, trailing white space is removed from 
the end of the string. Copying uses memmoveO because it properly handles 
overlapping areas of string arguments. 


88 


92-12 


8.2 The strdupO Function 

This function originally appeared in Kernighan and Ritchie [26] under the name 
strsaveO . The same function later appeared in an ANSI C Standard draft 
document and in various C run time libraries under the name strdupO. My 
current Standard draft [27] has deleted this function, so I wrote my own, to 
make sure I could port things from one C to another. 




STRUG 

strdup(s) /* get enough storage for s and put s there, 

return pointer to the string, or IIL if no 
string space. 


const STRIIG s; 

{ 

STRIIG p ■ IIL; 

if (s AID (p ■ *alloc(strlen(s) ♦ 1))) 
strcpy(p, s); 
return p; 

> 
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8.3 The strfnbO Function 

This simple function just skips any white space that appears at the beginning 
of the string parameter and returns a pointer to the first iionblank character 
(or to the NUL, if no nonblanks exist, or returns NIL if the given string does not 
exist). The function is similar to stratrimO, but the latter actually removes 
white space; strfnbO does not. 

STRUG 

strfnb(s) /• Return a pointer to the first nonblank character 

in string s, or to the IUL if • is e»pty 

/• 0/ 

STRIIG ■ ; 

if (s) 

while (isspace (•*)) 
return s; 

> 


90 


92-12 


8.4 The strinsertO Function 

This function inserts one string at the beginning of another. The algorithm is 
simplified using memmoveO, which is guaranteed to transfer characters despite a 
possible memory overlap. First the contents of s are shifted right by the length 
of t. Moving one character more than the length of 8 ensures that the s will 
still end in HUL. Then, t is inserted at the beginning of s: 




STRIIG 

atrlnaert (a, t) /* Inaert atring t in atring a at the baginning. 

Return a pointer to a. 

/* $/ 

STRIIG b , t ; 

{ 


aize.t n; 

MDOT6 ( a ♦ (n * atrlan(t)) , a, atrlan(s) + 1); 

■encpyCa, t, n) ; 
return a; 

> 

It is noteworthy here that the memcpyO function copies only the n characters 
of t, and not its terminating HUL, into s. 


Br 

£ 


| 
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8.5 The strlwrO Function 

This function rewrites the given string using lowercase alphabetic characters 
wherever capitals appear. Some C libraries contain this non-ANSI function, 
while others do not. To promote portability, 1 wrote my own version. 


STRUG 

strlor(s) /* Sat s to losarcase and return ■ . 


STRUG s ; 

{ 

STRUG p; 
if (s) 

for (p * a; ap ■ tolower(*p); p++) 

I 

return s ; 

} 
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8.6 The strnsetO Function 

This function replicates a given character a specified number of times into a 
string parameter, and returns a pointer to this string. This function also appears 
in some C libraries, but not in all, so I included it in mine, just to make sure. 


STRIIG 

strnsst(s, c, n) /* Return string * composed of n chsrsctsr c’s. 


STRUG s; 

n; 

{ 

STRIIG p; 

for (p ■ a; n — > 0; *p++ * (CHAR) c) 

♦p * IUL; | 

return s ; j 

> I 
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8.7 The strtcpyQ Function 

I wrote strtcpyQ to correct a misconception I had about what the ANSI 
stracpyO function does. I believed that it copied one string into another for 
a maximum of n characters, returning the copied string. It does not. Rather, 
strncpy(s, t » n) copies n characters from string t to string s and then stops. 
If no terminating HUL is encountered, none is copied. Thus, if n is greater than 
the length of the old s, but shorter than the length of t, then the HUL in s is 
overwritten and none is copied from t. The result is that s has been turned into 
garbage. My strtcpyQ, on the other hand, is a truncated copy that always 
puts in a terminating HUL into s. 



STRUG 

strtcpyCs, t, n) /* Truncated string copy. Copy at Boat n CHAR* 

of t into s, and return s. lote: in contrast 

to strncpyO , the returned copied s always ends 
in YUL . 



STRUG s ; 

const STRIYG t ; 

size.t n; 

{ 

size.t ■; 
if (s) 

{ m * strlen(t) ; 

■) ; 

t , n) ; 

YUL; 

return s; 

> 


n * HIYCn, 

■esBoveCs , 

*(s ♦ n) » 
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8.8 The strtrimO Function 

The strtrimO function is invoked directly by fgetstrO of Section 7.26, and 
also by stratrimO of Section 8.1. No algorithmic explanation is deemed nec- 
ess ary. 


STRIIG 

atrtrin(a) /♦ Tri* trailing ahita apaca trcm a and ratnra a. 


STRIIG a; 

{ 

FAST STRIIG p; 
if (a AID *a) 

for (p - atrlch(a) ; iaapaca(*p> AID p >■ a; p~ ) 
*p ■ IXIL; 

ratuxn a; 

> 
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9 MAINTAINING THE Coi^oin PROGRAM 

The Corffoin system described here — documents and code — are automatically 
built by .MAK files (See Appendix B). When it is time to process a report or 
other document within the system, the user engages the HAKE facility, which in 
turn calls the compiler, TeJC, and other special processors that create updated 
products. 

These files may require alteration to conform with the user’s development en- 
vironment, whenever a different compiler, directory structure, or set of utilities 
is present. 


II ttlllili III liill I liiillilllittlllillLiiiltii I: 



92-12 


97 


10 ERROR MESSAGES 

Error messages take the form 
file line offset message 

where file names the source file in which the error occurs, line is the offending 
line, offset is the approximate character on line where the violation occurs, and 
message is a diagnostic message. Such error forms can be used by some text 
editors for automatically placing the cursor on the lines for correction. 

(1) Beginning match string not found: match_string. 

The given match_string could not be found in the file named on the 
^access directive. 

(2) Break string is invalid: break. 

An invalid break string has been detected. This occurs when no instance 
of the break string is found on the '/.access directive line. 

(3) Command line error: 

An error on the invoking command line has been detected. File name and 
location information is omitted. Causes of this message are 

• Unknown option. The command line has a string argument begin- 
ning in */* or ' that is not recognized as an option. 

• Unknown command . The command line has a string argument unrec- 
ognized as either source or target file name. 

• Ho such file or directory. The file cannot be located. 

(4) End-match string not found: match jstring. 

The given ending match^string could not be found in the file named on 
the '/.access directive. 

(5) Input and output files may not be the same: name . 

The target file is not permitted to overwrite the source file. File name and 
location information is omitted from the message. 

(6) Memory insufficient for queue. 

Memory is unavailable from mallocO to queue the '/.access stream. 
MAX_Q may be set too large, or too many “terminate and stay resident” 
programs may be in memory. Try removing some of the TSR’s, or failing 
that, recompiling Coxffoin with a smaller HAXJJ. 

(7) No access file found: name. 

The file name given in the '/.access directive could not be found. Check 
the file name, its spelling, and '/.path directives for locatability. 
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(8) Ho lines copied from accessed file. 

'/.access has failed to transcribe anything from the file named in the 
directive. This often happens as a result of misspelling in the starting 
match_string . The error message is also put into the target file. 

(9) Range separator missing. 

The '/.access directive has the range_separator absent between the two 
match-strings. 

(10) Size command case invalid: case . 

A '/.size case other than C, a, T or r has been detected. A zero is substi- 
tuted into the text at this point. 
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APPENDICES 


A 

Corbin PROGRAM LISTING 


•define VERSIOI " (08- Apr-1992)" /* (Conjoin. c)*/ 

char copyrightnotice[14] [76] ■ 

•» 

u« 

ii« 

iif 

Copyright (C) 1992, California Institute of Technology 
All rights reserved. U. S. Government sponsorship under IASA 
Contract IAS7-918 is acknowledged. 

•**, 

•", 

•", 

•"» 

"• 

•'» 

"« 

iig 

Robert C. Tausworthe 
Jet Propulsion Laboratory 
4800 Oak Grove Drive 
Pasadena, CA 91109-8099 

•", 

•", 

•", 

•", 

1191 

•", 

!•«•••" , 


>; 

/* 

A1SI 5TAIDARD BEIDER FILES */ 


•include <ctype.h> 
•include <errno.h> 
•include <stdlib.h> 
•include <string.h> 
•include <stdio.h> 
•include <time.h> 


/• 


DEFIIITIOIS 


typedef int BOOL; 

typedef unsigned char CHAR; 

typedef unsigned char * STRUG; 

•define GLOBAL extern 

•define LOCAL static 


•define IIL 
•define 1UL 


((void *) 0) 
0 


•define FALSE 0 

•define TRUE 1 


*/ 
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•define HD A* 

•define IS -« 

•def ine IOT I 

•define HOD X 

•define OR I I 

• ifndef FILEIAKE.HAI 
•define FILEIAHE.HAX 50 

•end if 

•define HAX.COITEXT 10 

•define KAI.LIIE 135 

•define HAI.Q 100 

•define IUHBER.OF.PATHS 20 
•define PAGE. WIDTH 75 

•define OPEI.COHHEIT 
•define CLOSE.COKMEIT 
•define COKHEIT.LEIGTH 10 

•define ACCESS.SIGIAL OPEI.COHHEIT "acews" 

♦define BREAK. SIGIAL OPEI.COHHEIT "break" 

•define COLUHI.SIGIAL OPEI.COHHEIT "coln*n" 

•define COURT .SIGIAL OPEI.COHHEIT "count" 

•define GARBAGE.SIGIAL OPEI.COHHEIT "garbage" 

•define PATH.SIGIAL OPEI.COHHEIT "path" 

•define POSTFIX. SI GIAL OPEI.COHHEIT "postfix" 

•define PREFIX^SIGIAL OPEI.COHHEIT "prefix" 

•define RAIGE.SIGIAL OPEI.COHHEIT "range" 

•define SHQV.SIGIAL OPEI.COHHEIT "ebon" 

•define SIZE.SIGIAL OPEI.COHHEIT "size" 

♦define TAB.SIGIAL OPEI.COHHEIT "tabs" 

♦define BREAK. DEFAULT 
•define COLUHI.DEF AULT 0 

♦define COUIT.DEFAULT "•" 

•define GARB AGE.DEF AULT >t> 

•define OLD.TYPE.DEFAULT ".T.I" 

•define POSTFIX. DEFAULT "Wend" "{eerbatije}}" 

•define POSTVERBATIH "l\n\n" 

•define PREFIX. DEFAULT "{\\f ootnotesize \\begin{TerbatiM>" 

•define PREVERBATIH "\\no indent Weerbl" 

•define RAIGE.DEFAULT 
•define SHOW.DEFAULT FALSE 

•define TAB. DEFAULT 8 

•define TGT.TYPE.DEFAULT ".TeX" 

•define BGI.HATCH.ERR 0 

•define BREAK .ERR 1 

•define CHD.LIIE.ERR 2 

•define EID.HATCI.ERR 3 

♦def ine 10. SAKE .ERR 4 

•define HEHORY.ERR 5 

•define 10 .ACCESS. ERR 6 

•define IO.COPY.ERR 7 

•define RAIGE.ERR 8 

•define SIZE. ERR 9 
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•define FGETSIZE(a) 8trdup(atrtrin(fgeta(a , HAX.LIIE, aize.atream) ) ) 

/• * 

TOP-C FUICTIOI PROTOTYPES */ 


GLOBAL STRUG atratrim(STRIIG) ; 

GLOBAL STRUG atrdnp(STRIIG) j 

GLOBAL STRUG atrf nb(STRIIG) ; 

GLOBAL STRUG atrinaert (STRIIG, STRUG); 

GLOBAL STRIIG atrlwr (STRIIG) ; 

GLOBAL STRIIG atraaet (STRIIG , int, int); 

GLOBAL STRIIG atrtcpy (STRIIG , STRIIG, int); 

GLOBAL STRIIG atrtrim(STRIIG) ; 


/*- 


int 


FUICTIOI PROTOTYPES 
main (int, STRIIG [ ]); 


e 

*/ 


LOCAL BOOL acceaa (STRIIG) ; 

LOCAL BOOL access.condition(STRIIG , STRIIG [ ], int *, int •, int); 

LOCAL void announce (to id) ; 

LOCAL void coa»andJLine(int , STRIIG [ ], STRIIG); 

LOCAL BOOL ConJoin.f ilea(void) ; 

LOCAL BOOL copy.to.end_match(FILE *, STRIIG [ ], int, int); 

LOCAL BOOL directive (STRIIG, STRIIG); 

LOCAL void error_neaaage(int , STRIIG, BOOL); 

LOCAL STRIIG fgetstr (STRIIG , FILE *) ; 

LOCAL void f ile.def aulta(void) ; 

LOCAL FILE * file_open( STRIIG, STRIIG); 

LOCAL STRIIG right^f ill (STRIIG , int); 

LOCAL BOOL match.parametera ( STRIIG , STRIIG, STRIIG [ ], STRIIG [ ], 

int *, int *, int*, int *) ; 

LOCAL FILE * open.acceaa (STRIIG) ; 

LOCAL void open.io.f ilea(void) ; 

LOCAL void initialization (int , STRIIG [ ]); 

LOCAL STRIIG pntline (STRIIG ) ; 

LOCAL BOOL 8can_to _bgn_«atch(FILE *, STRIIG [ ], int, int); 

LOCAL STRIIG atrert (STRIIG, STRIIG); 

LOCAL void t imeat amp (void) ; 

LOCAL void nsage(void) ; 


/* 

LOCAL DATA STRUCTURES 
LOCAL long acceaa. lines ; 

LOCAL CHAR cloae [COHNEIT.LEIGTH] » CLOSE _ C OMMEIT ; 

LOCAL int column * CQLUMI. DEFAULT; 

LOCAL CHAR ConJoin.f ile[FILEIAME.HAI] * " H ; 


e 

•/ 
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LOCAL 

long 

ConJoin.lines; 


LOCAL 

FILE * 

Conjoin. stream 

■ IIL; 

LOCAL 

STAXVG 

count signal 

- COURT. DEFAULT; 

LOCAL 

BOOL 

credits 

■ TRUE; 

LOCAL 

CHAR 

garbage 

* GARB AGE. DEFAULT 

LOCAL 

STRI1G 

last.acc.lines 

■ RIL; 

LOCAL 

STRUG 

last.CJn.linas 

■ RIL; 

LOCAL 

STRUG 

last. tgt.lines 

- IIL; 

LOCAL 

STRUG 

last .use. lines 

■ RIL; 

LOCAL 

CHAR 

mark [10] 

- BREAK. DEFAULT ; 

LOCAL 

CHAR 

open [COKHEIT.LERGTH] 

■ OPER.COMKEIT; 

LOCAL 

STRIIG 

path. list [IUMBER.0F.P1THS] 

> 9 

LOCAL 

int 

path. list. size 

• 0; 

LOCAL 

CHAR 

post f ix [HAX.LIIE] 

- PQSTFIX.DEFAULT 

LOCAL 

CHAR 

post verbatim [30] 

- PpStVERBATni ; 

LOCAL 

CHAR 

prefix [MAI.LIIE] 

» PREFIX. DEFAULT; 

LOCAL 

CHAR 

preverbat im[30] 

» PREVERBATIM; 

LOCAL 

CHAR 

range [10] 

- RARGE. DEFAULT; 

LOCAL 

BOOL 

show 

■ SHOV.DEFAULT; 

LOCAL 

CHAR 

size.f ile [FILER AHE.HAX] 

» ,,n i 

LOCAL 

CHAR 

spaces [HAX.LIIE] 

* 

LOCAL 

int 

t abwidth 

» TAB. DEFAULT ; 

LOCAL 

CHAR 

tgt.f ile [FILEIAHE.HAI] 

m liii * 

LOCAL 

long 

tgt.lines; 

- - 

LOCAL 

FILE ♦ 

tgt. stream 

• IIL; 


/• aain */ 

/*•♦***• 

main (urge , argv) /♦ Process a Con Join file to craata a targat file. 

Return a FALSE value if no failure occurs, or 
TRUE or other nonzero value if a failure was 
encountered . 

- - */ 

STRUG argv[ ]; 

{ 

BOOL failure; 

FILE ♦size. stream; 
int i; 

init ializat ion(argc , argv); /• terminates if no source file named •/ 

open.io.f ilesO ; /♦ terminates on failure in opening files •/ 

access. lines m ConJoin.lines ■ tgt.lines * 0; 
timestampO ; 

failure * ConJoin.f ilesO ; 

failure I* fclose(ConJoin.stream) | fclose (tgt. stream) ; 
for (i * 0; i < path.list.size ; i++) 
free(path.list [i] ) ; 
free(last.acc.lines) ; 
free (last.CJn. lines) ; 
free (last. tgt .lines) ; 
free (last. use. lines) ; 

printf ("Processed: \nXl Old %s source lines\nXl01d accessed lines\n M 
"XlOld %s total lines written\n‘\ ConJoin.lines, ConJoin.file, 
access. lines , tgt.lines, tgt.f ile) ; 
if (size.stream * fopen(size_f ile , "w")) 
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{ fprintf (size. stream, "Xld\n%ld\n%ld\nfc.3f\n M , ConJoin.lines , 

access.lines , tgt. lines, 

(double) access.lines / (double) tgt .lines) ; 
failure |» f close (size. stream) ; 

} 

return failure; 

> 

/* end main ♦/ 

/* initialization */ 



▼oid 

initializat ion(argc , argr) 

/* Process command line file names and options, and retries# 


size.file statistics. 

/* / 

STRUG argv [ ] ; 

{ 

CHAR msg[HAX.LIIE]; 

STRUG s ; 

FILE *size. stream; 


} 

/ 


command_line(argc , argT, msg) ; 
announce () ; 
if (*msg) 

{ usage (); 

error.*essage(CHD.LIIE.ERR, msg, FALSE); 
exit (TRUE); 

> 

f ile.def aultsO ; 

if (I0T strcmp (ConJoin.f ile , tgt.file)) 

{ strcpyCmsg, ConJoin.f ile) ; 

•ConJoin.f ile * IUL; 
usage () ; 

error_message(IO_SAHE_ERR, msg, FALSE); 
exit(TRUE); 

> 

strcpy(strchr(s * atrcpy(size_f ile, tgt.file), * .*), ".siz"); 
if (size. stream * f open (size. file , "r")) 

{ last. CJn. lines * FGETSIIE(msg) ; 

last.acc. lines * FGETSIZE(msg) ; 

1 as t.tgt. lines * FGETSlZE(msg) ; 
last.use. lines » FGETSIZE(msg) ; 
f close (size. stream) ; 

> 

/* end initialization */ 

/• cohi and. line •/ 




▼oid 

comand_line(argc , argr, msg) 

/* Process information on the command line: extract ConJoin.f ile 
and tgt.file names, and option -a, when present. Return with 
msg set to error conditions. 

/. ./ 

STRUG arg. [ ] , msg ; 
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int i; 

STRIIG a; 

•msg * IUL ; 

for (i ■ 1; i < argc; i+-0 
{ a * atrlwr(argr[i]) ; 

if (*s IS *-» OE *s IS >/*) 

{ switch (*++•) 

{ cut »•»: 

credits * FALSE; 
brtik; 
default : 

sprintf (mag ♦ strlen(msg) , "Unknown option: 
"%s . \n" , argr [i] ) ; 

> 

*argr[i] * IUL; 

> 

else if (I0T •ConJoin.file) 

strcpy (Con Jo in _f ila , a); 
else if (I0T *tgt_file) 

strcpy (tgt. file, a); 

else 

sprintf (mag + strlan(msg), "Unknown command: Xa.\n" 


8>i 


> 

if (JOT *ConJoinjfile) 

strcatCmsg, "lo source file named. \n") ; 

/* end coBtand.line */ 


/» announce */ 
eeeeee* •*****•/ 


to id 

announce () 


/* Announce program, copyright, and author. 


/*- 

{ 


-•/ 


int 


if (credits) 

{ for (i * 0; •copyrightnotice[i] ; i++) 

printf ("Xs\n", copyrightnotice[i]) ; 
printf ("\n\t\t\t Conjoin Program" 

"\n\t\t\t Xs\n\n". VEESI01) ; 

} 


/* end announce a/ 


/e err or ^message ♦/ 


Toid 

error .message (n , a, f) /* Write error message n augmented with string a 

to stdout , indicating the current line in the 
source file. Eepeat the message on the target 
file if f is TEUE. 

7 

STEIIG s; 
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LOCAL STRUG errmsgC ] * 

{ "Beginning Batch string not found: ", 

"Break string is invalid: ", 

"Command line error: ", 

"End-match string not found: ", 

"Input and output files may not be the same: " f 
"Memory insufficient for queue.", 

"lo access file found: ", 

"Io lines copied from accessed file.", 

"Range separator missing.", 

"Size comird case invalid: " 


} 

/> 


if (*ConJoin_f ile) 

printf ("\a%s , Xld 1: %sXs\n" , 

Conjoin. f ile , Con Jo in .line* , ermsg[nj , s); 

else 

printf ("XsXs\n" , errmsgCn] , s); 

if (f) 

fprintf (tgt. stream, "***ERR0R*** %s%s\n", errmsg[n] , s) ; 


void 


/* end error.message */ 


/♦ usage ♦/ 
****,«***,/ 


us age O 


/* Print a message on usage syntax of Conjoin. 


/* 

{ 


> 

/' 




printf ( "Usage : Conjoin <ConJoin source> <target file> " 

" [<options>] \n\n" 

"\tSource file type default is .CJn\n" 

"NtTarget file type default is Xs\n\n" 

"Options :\n" 

"\t-a Do not announce the program. \n", TGT.TYPE.DEFAULT) ; 

/• end usage */ 

/* f ile.def aults */ 


void 

f ile.def aults () /* Supply Conjoin file type .CJn if missing, and 

supply missing parts of tgt.file, if any. 

/* - ♦/ 

{ 


STRIVG s ; 


if (I0T (s * strchrCConJoin.file, 9 .*))) 
s treat (ConJo in. file , ".CJn"); 
if (I0T *tgt .file) 

{ strtepy (tgt .file, ConJoin.file, 

strchr(ConJoin.file , * .*) - ConJoin.f ile) ; 

} 

if (I0T (s ■ strchr(tgt_f ile , * .*))) 

streat (tgt.file , TGT. TYPE. DEFAULT) ; 
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/• *nd fil«. defaults •/ 

/• opan_io_fil«s •/ 


▼oid 

open.io.f ilesO /• Open ConJoin.f ile and tgt.file into ConJoin.stream 

and tgt. stream. Rename old tgt.file, if any, 
with OLD .TYPE. DEFAULT . Torminato with an arror 
message via file.openO if files cannot ba opanad. 


{ 

CHAR tgt _bak[ FILER AKE.MAI] ; 
FILE • f ; 

STRUG s; 


Conjoin. stream * f ile_open(ConJoin.f ila , "r“) ; 
if (f * fopen(tgt.f ile , "r")) 

{ fcloseCf ) ; 

s ■ strehr (strcpy(tgt_balc, tgt.file), ».'*); 
strcpy(s , OLD. TYPE. DEFAULT) ; 
remove (tgt.bak) ; 
rename (tgt .file, tgt.bak) ; 

> 

tgt. stream * file.open( tgt .file, "a”); 

/* end open.io.files */ 

/* file. open •/ 


FILE * 


file. open (name , nse) 

/♦ Open the name file for given nse, and return resulting stream. 
If file cannot be opened, print reason, and abort processing. 
/• * * 


STRUG name, use; 

{ 

CHAR sOiAX.LIIE] ; 
FILE * stream; 


if (I0T (stream * fopen(name, use))) 

{ strcpy(s, name); 

♦name * IUL; 

strncatCstrcat (s , "), strerror(errno) , HAX.LIIE - 1) ; 

error.message(CMD.LIVE.ERR, s, FALSE); 
exit (TRUE); 


return stream; 


/* end file. open */ 


/* t imest amp *f 


▼oid 


timestampO /* Write the tgt.file name and a time-stamped header with 
a revision warning onto the tgt .stream. 

/ 

{ 
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tine.t 

CHAR 


STRUG 
struct tm * 
int 


clock; 

atime[26] , 

bar[HAI.LIIE], 

blank a [HAI.LIIE] ; 

ap, text; 

t; 

n; 


} 


n * atrlen(open) + atrlen(cloae) ; 
strnset(bar, PAGE.WIDTH - n) ; 

at meet (blanks , * ' , PAGE.WIDTH - n - 2); 
time(Aclock) ; 
t * localtime (Aclock) ; 
stratrim(strcpy(atime, aactime(t) ) ) ; 
ap * right.filKatime, strlen(tgt_f ile) ♦ n ♦ 5) ; 
fprintf (tgt. stream, "Xs (Xs)Xs(Xs)Xs\n M , open, atime, ap, 
tgt .file, close); 

fprintf (tgt. stream, "XsXaXs\n" , open, bar, close); 

text * "Xsl This file oas ConJoin-ed from input file %s .%s IXs\n M ; 

ap * right.fill(text , strlen(ConJoin_f ile) - n - 7) ; 

fprintf (tgt .stream, text, open, ConJoin.f ile , ap, close); 

fprintf (tgt.st ream, "Xs (Xs [Xs\n", open, blanks, close); 

text » "%s| DO I0T REVISE THIS FILE.Xs|%s\n"; 

fprintf (tgt. at re am, text, open, right .fill (text , n - 7) , close); 

fprintf (tgt .stream, *'Xs IX»IXs\n M , open, blanks, close); 

text « "Xal To make revisions, modify the original file .%a |Xa\n"; 

fprintf (tgt.stream, text, open, right.f ill (text , n - 7) , close); 

fprintf (tgt.st ream, "XsXsXaXn" , open, bar, close); 

tgt.lines +* 8; 


/* end timestamp */ 


/* right.fill •/ 



STRUG 

right.fill (s, n) /* Generate spaces as a blank string of length 

PAGE.WIDTH - n. Return spaces. 

/* •/ 

STRUG s; 

{ 


return strnset (spaces , ’ ’ , PAGE.WIDTH * strlen(s) - n) ; 

> 

/• end right.fill */ 

/* Con Jo in. f ilea •/ 




ConJoin.f ilea () /* Process the Conjoin source file and create the 

expanded target file. Return a nonzero value 
if an error occurs , or a 0 value if none . Count 
Con Jo in. line s, access. lines, and tgt.lines. 

/• •/ 

{ 

BOOL error ; 

CHAR hold [HAZ .LIVE] , 
line [HAI.LIIE] ; 
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STKIIG extract ; 

error * FALSE; 

♦spaces ■ IUL; 

for (Con Jo inclines ■ 0; fgetsCline, HAX.LIIE, ConJoin.stream) ; > 

{ ConJoin_lines++; 

tgt.lines++; 
if (I0T *strfnb(line)) 

{ fprintf (tgt.stream, M Xs'\ line); 

continue ; 

> 

if (strstrCline, open)) 

{ if (extract * strstrClins, ACCESS.SIGIAL) ) 

strcpy(hold, line); 
error I* directive(extract , line); 

> 

else 

extract * MIL; 

fprintf (tgt.stream, "Xs", line); 
if (extract) 

error I* access (hold + (extract - line) + 
strlen(ACCESS.SIGIAL) ) ; 

> 

return error; 

/• end ConJoin.f iles */ 

/* directive */ 


BOOL 

directive(extract , text) 

/* Process Conjoin directives that Kay appear in the text string. 
Xf extract is non^IIL, the text contains an access directive 
that may only need to be prepared for showing. In case of 
Xsize, write the appropriate values into text. Insert 
preverbatim and postverbati* into text if show is, or has just 
turned, TRUE. Return TRUE if a bad Xsize case appears; FALSE 
otherwise . 


STRUG extract, text; 

{ 

STRIIG s, 

t; 

CHAR g, 

line [HAX.LIIE] ; 

BOOL change. show; 

strcpy(line, text); 
if (extract) 

t ■ line + (extract - text); 
else if (t * strstrCline, BREAK. SIGIAL)) 

strext (mark, t + strlen(BR£AK. SIGIAL)) ; 
else if (t * strstr(line, COLUMI. SIGIAL) ) 

{ column * atoiCt + strlen(COLUHM.SIGIAL) ) ; 

if (column > 0) 

{ st rnset (spaces, ’ 1 , column); 
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column * 0; 

} 

else 

♦space* ■ IUL; 

} 

else if (t * strstr (line, COURT. SIGIAL)) 

strext (count signal „ t + strlen(COUIT.SIGIAL) ) ; 
else if (t - strstr (line , G ARBAGE.SIGIAL) ) 

{ if (g * •strfnb(t + strlen(GARBAGE.SIGIAL) ) ) 

garbage - g; 

> 

else if (t * strstr (line, PATH.SIGIAL)) 

{ pat h.list [path _list.size++] ■ 

strdupCstrert (t , t + strlen (PATH.SIGIAL) ) ) ; 

> 

else if (t - strstr (line, POSTFIX.SIGIAL)) 

strext (postfix, t + strlen(POSTFIX.SIGIAL)) ; 
else if (t - strstr(line, PREFIX. SIGIAL)) 

strext (prefix, t + s trlen( PREFIX. SIGIAL)) ; 
else if (t - strstr (line, RAIGE.SIGIAL) ) 

strext (range , t + s t rlen (RAIGE. SIGIAL)) ; 
else if (t - strstr (line, SHOW.SIGIAL)) 

{ s * strlwr(stratrim(t + strlen(SHOV.SIGIAL))) ; 

if (I0T strcnp(s, "on")) 

change .show * TRUE + TRUE; 
else if (I0T 8trcmp(s, "off")) 

change.show * TRUE + FALSE; 
if (change.show AID 10T shoe) 

show * change. show - TRUE; 

} 

else if (t * strstr(line, SIZE.SIGIAL)) 

{ do 

{ *t * IUL; 

switch (*(t * strfnb(t + strlen(SIZE.SIGIAL)))) 
{ case ’c>: 
case , C > : 

s * last.CJn.lines ; 
break; 
case ’a } : 
case ’A 1 : 

s * last. acc. lines ; 
break; 
case ’r’: 
case J R>; 

s * last .use .lines ; 
break; 
case *t 9 : 
case } T 1 : 

s * last.tgt. lines ; 
break; 
default : 

s * "0"; 

error_message(SIZE_ERR, text, FALSE); 
return TRUE; 


> 
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sprintf (text , M %s %s%s", line, s, ++t) ; 

> while (t ■ strstr(strcpy(line , text), SIZE.SIGIAL) ) ; 

} 

else if (t * strstr(line, TAB.SIGIAL)) 

tebwidth * atoiCt + strlen(TAB.SIGIAL)) ; 
if (t AID show) 

{ st r insert (text + (t - line), preverbatim) ; 

if (eclose AID (t - strstr(text, close))) 
strinsert (text , postverbatim) ; 

else 

strcat(stratrim(text) , postverbatim) ; 
if (change .show) 

show * change. show - TRUE; 

} 

return FALSE; 


> 


/*««******♦***> 

STRUG 
strext(s, t) 


/* 


/* end directive */ 


/* strext */ 
.*♦******♦♦*/ 


/* Extract string t up to the close-comment string, if close 
is not null, or to the end of t if null, into s. Remove 
leading and trailing blanks from s and return s. 


STRIIG s, t; 

{ 

STRIIG p; 


if (eclose AID (p - strstr(t , close))) 
strtcpy(s, t , p * t) ; 

else 

strcpy(s, t); 
return stratrim(s) ; 


/e end strext */ 

/e access e/ 


BOOL 

access (buffer) /• Process the text extraction operation specified 

in the line buffer to the tgt.stream. Return 
FALSE if no error, TRUE if an error occurred. 


STRIIG 

{ 


buffer; 

STRIIG bgn_match[HAX_COITEXT + 1], 

end .match [MAX _C0 I TEXT + 1] ; 
CHAR module [FILEIAHE.HAI] ; 

BOOL error; 

FILE * module st re am; 
int bgncount , 

bgnoff set , 
end count , 
endoff set , 
i; 
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strext (buffer, buffer); 

if (match.parameters (buffer , modal*, bgn.match, end.match, Abgn count , 
Abgnoff s*t , Aendcount , Aendoffset)) 
return TRUE; 

if CVOT (modulestream * open.access(modula))) 

{ error.messaga (10. ACCESS. ERR, module , FALSE); 

return TRUE; 

> 

printf ("Xsaccess XsXs\n M , open, buffer, close); 
if (*prefix) 

fprintf(tgt .stream, “Xs\n" , prefix); 
error * scan_to.bgn_natch(nodulestrean, bgn.match, bgn count , 
bgnoffset) ; 

error I* copy.to_end_match(modulestream, end. match , endcount, 
endoffset) ; 

for (i * 0; bgn_match[i] ; i++) 
free(bgn_match[i] ) ; 
for (i * 0; end_match[i] ; i++) 
free(end.match[i] ) ; 
error I* fclose (modulestream) ; 
if (*postfix) 

fprintfCtgt .stream, "%s\n" , postfix); 
return error; 

} 

/* end access */ 

/* match.parameters */ 

* 

BOOL 

mat ch.parameters (buffer , module, bgn_match, endjmatch, bgn count , bgnoffset, 
endcount, endoffset) 

/* Extract access module name, and beg in n i ng and ending access 
conditions. Return TRUE if an error is encountered, FALSE 
otherwise . 

/* */ 

STRUG buffer, bgn_match[ ], endjmatch [ ], module; 
int *bgncount, ebgnoffset, *endcount, *endoff set ; 

{ 

CHAR line [KAI.LIVE] ; 

STRUG s , 
t ; 

if (I0T (s * strstr(strcpy(line , buffer), mark))) 

{ error .message (BREAK. ERR, buffer, FALSE); 

return TRUE; 

> 

st rat rimC st rtepy (module , line, s “ line)); 
if (I0T C ♦ ( t * strfnbCs + strlen(mark))) 

AID (s * strstrCt , range)))) 

{ error .message (RAIGE.ERR , buffer, FALSE); 

return TRUE; 

} 

•s * IUL ; 

s +* strlen (range) ; 

if (access. condition(t , bgn .match, bgneount, bgnoffset, 1)) 
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return TRUE; 

if (acc*si_condition(s , •nd.utcfc, •ndconnt, andoff »«t , -1)) 
return TRUE; 


> 


return FALSE; 


/• end match.parameters */ 


/• access .condition */ 


/•*♦*♦< 

access. 


BOOL 

condition (buffer, match, count, offset, init) 

/• Extract access condition from buffer. Set offset to init if 
no offset is parsed in the buffer. Return TRUE if an error 
is encountered, FALSE otherwise. 


/* 

STRUG 

int 

{ 


-*/ 


buffer, natch[ ]; 
•count, *off set ; 

int n; 

STRIIG s, t; 


•offset ■ init; 

•count * 1; 

s * stratrim(buffer) ; 

if (t * strstrCs, count signal)) 

{ •count * atoi(s * t ♦ strlen(countsigaal)) ; 

•t * IUL ; 

if (<t - strchrCs, >♦*)) OR (t ■ strchr(s, »-'))) 

{ ^offset * atoi(t); 

•t * IUL; 

> 

else if (isdigit (*buff er)) 

{ •offset » atoi(buff er) ; 

•buffer * IUL; 


s * buffer; 

for (n * 0; *s AID n < HAI.COITEIT; n++) 

{ if (t * strstrCs, mark)) 

{ +t * IUL; 

t strlen(mark) ; 

> 

■atchfn] » strdupCstrtrin(s)) ; 
b * strfnbCt AID *t ? t : s + strlen(s)); 

} 

if (n > 0 AID matchCn - 1] IS IIL) 
return TRUE; 

match[n] * IIL; 
return FALSE; 


/* end access.condition •/ 


/• open. access •/ 
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FILE • 

open.access (f ile) /* Open the specified fil« for reading. 


STRI1G file; 

{ 

int i; 

CHAR path[FILEIAME.MAI] ; 

FILE • stream; 

strcpy(path, file); 

lor (i - 0; I0T (strou - fop.n<path, "r”)) AID i < path_liat_»iza; i«~0 
■treat (strepy (path, path_liat[i]) , fila); 
return stream; 

/* end open_access */ 

/• scan_to_bgn_match • / 


BOOL 

scan_to_bgn_match (modulestream, bgn.match, bgneount, bgnoffset) 

/• Scan the modulestream for the beginning match condition and 
return positioned to access the first line to be copied. 



FILE * modulestream; 

STRIVG bgnjmatch[ ] ; 

int bgneount , bgnoffset ; 

{ 

fpos.t fp, 

f pqueue [MAX.Q] ; 
int n, 

offset , 
qex; 

BOOL error; 

long qe ; 

CHAR t ext [KAX.LI VE] ; 

n M error * offset ■ 0; 
qe - -1; 

while (HOT fgetpos (modulestream, Rfp) AID 
f gets (text , MAX.LIIE, modulestream)) 

{ qex « (int) (++qe MOD KAI.Q) ; 

f pqueue [qex] * fp; 
if (bgn.match [n] ) 

{ if (I0T strstr(text , bgn_match[n])) 

continue; 

if (bgn_match[++n] ) 
cont inue; 

if ( — bgneount <■ 0) 

{ if (bgnoffset <* 0) 

{ qex * ( int ) ( (qe + bgnoffset) MOD MAX.Q) ; 

f setpos (modulestream, If pqueue [qex] ) ; 
break; 


} 
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«ls« if (bgnoffset IS 1) 
break; 

} 

•1st 

n ■ 0; 

> 

else if (SOT bgnoffset) 

{ fsetpos(modulestream, Rfpqueue CqexJ ) ; 

break; 

> 

else if (+*offset >■ bgnoffset) 
break; 

> 

if (bgn.match[0] AID bgn_match[n] ) 

{ err or .mess age (BG I. MATCH. ERR , bgn.match[n] , TRUE); 

error * TRUE; 

> 

return arror; 

/• end scan.to.bgn.match */ 

/* copy.to.end.match •/ 


BOOL 

copy to_and.match(*odulestream f end.match, end count , endoffset) 

”/* copy lines from modulestream to tgt.stream, up until the and -match 
condition is satisfied. Return TRUE if in error uas encountered, 
printing the appropriate error message; return FALSE otherwise^ 

FILE •modules t ream; 

STRUG end.match[ ]; 

int endcount , endoff set ; 

{ 

int count , 

error, 
offset , 
n, 

qbx, 

qex; 

long qb , 

qe; 

CHAR text [MAX.LIIE] ; 

STRIIG txqueue [MAX.Q] ; 

qe * -1; 

for (count « error ■ offset ■ 0; fgetstrCtext , modulestream) ; count**) 

{ if (endoffset <* 0) 

{ qex ■ (int) (**qe MOD MAX.Q) ; 

if (IOT (txqueue [qex] » strdup(text))) 

{ error .message (MEMORY. ERR, FALSE); 

error * TRUE; 
break; 

> 

if ((qb * qe + endoffset) >*0) 

{ qbx * (intXqb MOD MAX.Q); 
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free (put line(txqueue [qbx]) ) ; 
txqueue[qbx] ■ IIL; 

> 

if (end_*atch[n]) 

{ if (IOT strstr(text, end_*atch[n])) 

continue; 

if (end_aatch[**n]) 
continue ; 

if ( — end count <* 0) 

{ while (qb <» qe) 

{ qbx * (int)(qb+* MOD HAX.Q) ; 

free ( txqueue [qbx] ) ; 

} 

break; 

> 

else 

n - 0; 

> 

} 

else if (end_*atch[n] ) 

{ put line (text) ; 

if (IOT strstr(text, end_match[n] ) ) 
cont inue; 

if ( end_nat ch [++n] ) 
continue ; 


if ( — endcount > 0) 
n - 0; 

> 

else if (offset-*-* < endoffset) 
putline(text) ; 

else 

break; 

} 

if (end_match[0] HD end_»atch[n] ) 

{ error.me ssage (EID_HATCB_ERR , end_*atch[n] , TRUE); 

error * TRUE; 

> 

if (IOT count) 

{ error _»essage(IQ_COPY_ERR, TRUE); 

error * TRUE; 


> 


return error; 


/• end copy_to_end_match •/ 


/eeeeeeeeeeeeeeeee 

STRIIO 

fgetstr(s, streaja) 


/♦ fgetstr */ 
,*****»*eeeee/ 


/* 

STRIIG s ; 


/* Get string s f ro« the naaed stress with 
TABs replaced by spaces, and return it. 
•/ 
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FILE * 
{ 


stream; 

CHAR c, 

p[HAIJLIIE] ; 

int i, 

j; 

STRUG q, 

t; 

if CIOT (q - fgetsCp, MAI.LIIE, stream))) 
return IIL; 

for (t ■ s, i * 0; c * *q++; ) 

{ if (c IS >\t>) 

{ j ■ tabvidth - (i HOD tabwidth) ; 

while <J— ) 

{ *t++ - ' 

++i; 

> 

continue; 

> 

•lse if CIOT (isepaceCc) OR isprint(c))) 

C ■ garbage; 

*t++ ■ c; 
i++; 

> 

*t * IUL; 

return atrcat (strtrim(s) , "\n"); 


> 

STRUG 

putline(s) 


/•- * 

STRIIG a; 

{ 

STRUG 


/• end fgetstr */ 


/* put line */ 


/♦ Write the the string s onto the output stream, properly 
columnated . The string is presumed to exist and contain 
a newline. Count the output both as one of the 
access.lines and tgt. lines. 




t; 


if (s AID (t * strchrCs, , \n , ))> 

^ t * s + (column < 0 ? min (“column , t ~ s) : 0) ; 

fprintf (tgt .stream, "XsXs". spaces, t) ; 
access„lines++; 
tgt_lines++; 

} 

return s; 

/* end putline */ 


/* end program */ 
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B Conjoin CONSTRUCTION 

B.l The Master Document File 

X (30- Jul-1992) CCJ_r#prt .T*I) 

It • 


It 

It 

It 

It 

It 

It 

It 

It 

It 

It 


Copyright (C) 1992, California Institute of Tachnology 
ill rights reserved. U. S. Government sponsorship nndar liSi 
Contract IAS7-918 is acknowledged . 

Robert C. Tanswortha 
Jat Propulsion Laboratory 
4800 Oak Grove Drive 
Pasadena, CA 91109-8099 


It 

Xtttttttttttttttttttttttttttttttttttttttttttttttttttttttttttttttttttttttttt 


JPL REPORT FORMAT 


\document style [tans , too side] {art icla> X tans. sty is naadad because it 

X contains the box shapes for Figure 1 
X and the JPL Report format. 


\nevcoBnand{\path}{CJ_} 

\ input {\path style} 

\neucomnandi\Title} {Conjunct ire Programming: \\ An Integrative Approach to \\ 
Software System Synthesis} 

\newcon»and{\PubDate} {August 31 , 1992} 

\newcosmiand{\DocIumber}{92-12} 

\newcoHnand{\vork}{ report} 

\begin {document} 

X COVER PAGE 

\pagastyle{ empty} 

\coverpage{ JPL Publication \DocIumber}{\Title}{\Author}{\PubDate} 

% - FROIT MATTER STYLE 

\rm 

\pagestyle{my headings} 

\markbo t h{ \ Do c Vumbe r } { \ D o dumb a r} 

\p age numbering {roman} 

\setcounter{page}{2} 

%— f ASA AID OTHER CREDITS 

\ input {\path credt} 

X‘ 


ABSTRACT 
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Xrectopage 
Xputmidpage 
{ Xb eg in{ center} 

\large \bf AbstractXXC .3in] \»or»alsiz« 

\end{center} 

\begin{quotat ion} 

\ input {\path abatr} 

\end{quotat ion} 

} 


ackiovledgheit 


Xclearpage 

Xputmidpage 

{ 

Xbegin{center} 

Xlarga Xbf AcknoeledgementXXC 3in] Xnormalsize 
\end{center} 


Xbegin{quotat ion} 

X input {Xpath ackno} 
\end{quotat ion} 

} 


TABLE OF COITEITS 


Xrectopage 

\begin{center} 

XLarge \bf ContentsWC .5in} 
Xnormalsize 
\end{center} 


XTableof contents 

%- 


LIST OF FIGURES 


XT«pace*{0 .5in} 

Xbegin{center} 

{\Large \bf List of Figures} 
\end{center} 


\List off igure a 

^ LIST OF TABLES “ 

% I0TE: THIS SECTIOI IS COHMEITED OUT BECAUSE 10 TABLES CURJtEITLY 

% EXIST II THE REPORT. 

%XTspace*{0. Sin} 

%X*>egin{ center} x 

% {XLarge \bf \no indent List of Tables} 

X\end{center} 
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XNLiat of tables 

X BODY 

\rectopage 

\p agenunbe r ing{ ar ab ic } 

\set counter {sect ion}{0} 

\setcounter{page}{l} 

\ input (\path body) 

X APPENDICES 

\s act ionpaging 
\ appendix 
\begin{c enter} 

\Large \bf APPENDICES \xspace{ . Sin} 

\nornalsize 

\end{center} 

\addtocontents{toc}{\protect\¥space{Sex}} 

\addtocontents{toc}{} 

\addtocontents{toc}{\protect\begin{center}\protect\Large \protect\bf 

Appendices \protect\end{center}\protect\TSpace{5ex}\protect\noiMalsize} 
\addtocontents{toc}{} 

\input{\path. appxA} 

\sect ionpaging 
\ input {\path appxB} 

\sect ionpaging 
\ input {\path appxC} 

X - REFERENCES 

\sect ionpaging 
\input{\path bibl} 

X END OF DOCUMENT 


\end{docuaent} 
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B.2 The Program Compilation Script 


techo off 


r« (31-Jul-1992) (CJ.cods .b«t) 

rw »#*i»t##*#t***##*#M**##t##t*#****M***########**#**t#»#**#***********«*»» 
rem t 
ran * 
ran * 
ram * 

T0B * 

r«i i 
rem * 
rem t 
rim f 
ram i 
ram t 


Copyright (C) 1992, California Institute of Technology 
ill rights reserved. U. S. Government sponsorship nndar IlSi 
Contract IAS7-918 is acknowledged . 

Robart C. Tanswortha 
Jat Propulsion Laboratory 
4800 Oak Grove Drive 
Pas ad ana , Cl 91009-8099 


*#**»t*#*»**#****##******************* ,t **** ,M, * MM ** ###,##, * , * ,,,M,,#, 

la Conjoin onTironnent transformation for NIKE, and HAKE tha Conjoin 
r« Program. 


if azist CJ.code.mak goto ok 
acho lo fila CJ.code.mak 
goto fin 


sat up tha HAIE environment for locating includa files, libraries, 
tha tfiKE program, and tamporiry fila i/o: 


sat savepath*XpathT 

sat path*c:\c\mac5\bin;XsavepathX 

sat include*c : \c\ansi\h; c : \c\topc\h 

sat lib*c:\c\lib 

sat init=c :\c\msc5\bin 

sat tmp*c : \t«mp 

ram KIKE tha Conjoin program 
make CJ_code.mak 


ram rastora tha environment 

sat path*XsavepathX 
sat savepath* 
sat lib* 
sat tmp* 
sat include* 
sat init* 


:f in 


28882828888 
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B.3 The Program Compilation MAKE File 

t (31- Jul-1992) (CJ_cod« .ask) 

Copyright (C) 1992, California Institute of Technology • 

All rights reserved. U. S. Government sponsorship under IASA t 

Contract IAS7-918 is acknowledged. * 

Robert C. Taussorthe * 

Jet Propulsion Laboratory * 

4800 Oak Grove Drive • 

Pasadena, CA 91009-8099 • 


fffffffffffffffffffffffffffffffffffffffffffffffff****M*fffffffffffffffffff 

f Conjoin program construction instructions 

ConJoin.exe: Conjoin. c CJ^code. mak 

cl /V3 /Ox ConJoin.c /F 1000 /link /I0E stopc.lib; 
del Conjoin. obj 

The compiler is directed to print all warning messages and make the program 
internal stack size be 0x1000. The program is built using the small memory 
model, the compiler default. The automatic linking process searches the small- 
memory-model TOP-C library for the functions discussed in Section 8. 
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B.4 The Document Construction Script 


•echo off 

i'ab (31"Jul”1992) (CJ.doc - bit) 

r« ####*#*####»#»•••##*****»•**•#**#*##*•#«**##** 

re® 9 
re® 9 
re® 9 
re* 9 
re® 9 
re® 9 
res 9 
re® 9 
re® 9 
re® 9 
re® 9 


Copyright (C) 1992, California Institute of Technology 
All rights reserved . U. S. Government sponsorship under IASA 
Contract IAS7-918 is achnouledged . 

Robert C. Taussorthe 
Jet Propulsion Laboratory 
4800 Oak Grove Drive 
Pasadena, CA 91009-8099 




MAKE th« Conjoin usig« and antira docunant . 


make /I cj^usage .®&k 
make cj.doc.aak 

Two separate MAKE invocations are made. The first,* made under the /I 
option, causes MAKE to ignore an error return code from processors called by 
MAKE. This option is necessary, because CJ_usage.nak executes Conjoin with 
no command arguments, a condition that causes the usage message to print and 
the program to terminate with an error-indicating return code. The Conjoin 
output, in this case, is redirected into the CJ_usage.msg file for ’/.access into 
Section 4.2 of this document. 

The second MAKE invocation compiles and builds the document you are read- 
ing. 


S2S8288SS22 
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B.5 The Usage Message MAKE File 

• (31- Jul-1992) (CJ.iHp.«k) 

•**#»###»**»»#»•*#»«** 

Copyright (C) 1992, California Institute of Technology f 

111 rights reserved. U. S. Government sponsorship under VASA • 

Contract IAS7-918 is acknowledged. * 

Hobart C. Tausworthe * 

Jat Propulsion Laboratory * 

4800 Oak Grove Drive * 

Pasadana, CA 91009-8099 • 


t This is a saparata HAKE file bacausa it is axacutad with tha /I 
t option to ignore exit codas, bacausa Conjoin returns an error coda on 
• termination. 

CJ .usage .msg: Conjoin.exe 
Conjoin >CJ_ usage .msg 
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B.6 The Document MAKE File 


t (31-Jul-1992) (CJ.doc.M 

*M#»#M**mM*#«M*»«****»******» M, * # ** #m * ,,# *** M##m, ****** ,,i#,# 


•• 

tt 

tt 

tf 

ft 

ft 

tt 

ft 

tt 

tt 


Copyright CO 1992, California Institute of Technology 
All right* reserved. U. S. Government sponsorship nnder IASA 
Contract IAS7-918 is acknowledged. 

Robert C. Taussorthe 
Jet Propulsion Laboratory 
4800 Oak Grove Drive 
Pasadena, CA 91009-8099 


###*i«#*»m»#i«M**t*»»»***«*******»*** ,,MM,#,,, * , * ,##m##,,##t,# ** 


f Directory of TOP-C Functions 
topc*\c\topc\c\ t 


CJ.prog.cal: Conjoin. c CJ.prog.cal 

c alltree /c CJ.prog.cal /b CJ.prog.by Conjoin. c 

CJ.prog.by: Con Join. c CJ.prog.by 

~ c alltree /c CJ.prog.cal /b CJ.prog.by Conjoin. c 

CJ.prog.siz: Conjoin. c 

f lines Conjoin. c >CJ.prog.siz 

CJ.appxA.tex: CJ.AppxA.cjn Conjoin. c 
Conjoin -a CJ.appxA 

CJ.appxB.tex: CJ.AppxB.cjn CJ.reprt.tex cj.code.bat cj.doc.bat \ 
cj.code.nak cj.doc.mak 
Conjoin -a CJ.appxB 

CJ_appxC.tex i CJ.appxC.cjn CJ. prog. cal CJ.prog.by 
Conjoin -a CJ.appxC 

CJ.body.tex: CJ.body.CJn Conjoin. c CJ.style.tex CJ.nsage .msg \ 

CJ_figl.tex CJ.prog.siz $(topc)stratrim.c $(topc)strdup.c \ 
$(topc)strfnb.c $(topc)strlur. c $(topc)strtcpy .c $(topc)strtri*.c 
Conjoin -a CJ.body 

CJ.reprt.dvi: CJ.reprt.tex CJ.style.tex CJ.abstr.tex CJ.ackno.tex \ 

CJ_credt.tex CJ.body.tex CJ.appxA.tex CJ.appxB.tex \ 

CJ.appxC . tex CJ.bibl.tex CJ.doc.nak 
call latex CJ.reprt 
call dvi CJ.reprt 

The calltree program is a utility supplied with Microsoft C. It prints out 
call trees (structure diagrams) and reference trees (called-by diagrams). These 
appear in Appendix C. 
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The Hines utility scans the named file and writes the number of lines in 
that file normally to the console, but here to a size file accessed by CJ_ body .CJn. 

The CoTffoim program creates the .TeX versions of Appendices A, B, and 
C and the text body; the -a option suppresses printing of the JPL/Caltech 
copyright notice and program announcement. 

This report was then composed by the I^TjrX system, which is set up and 
executed called as a batch command, latex. 

This report was then printed by calling the batch command dvi, which 
converts the device-independent output of T^X into the typeset form that you 
are reading now. 
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C Co in FUNCTIONAL STRUCTURE 

C.l Call Tree 

The following listing denotes the invoked function structure of Corffoln in depth- 
first order. Multiple branches of the same subtree are not shown. Function 
names followed by C T are external to Coi^oin, and are either in the standard 
ANSI library or the TOP-C library. Although not functions, some defined 
terms, such as HIL, NOT, AND, and other spurious entries may appear in the 
listing because of a flaw in the Microsoft calltree utility used to generate the 
tree. 

VIL 

FGETSIZE 

atrdup 

atrtrim 

fg*ts 

main 

I initialization 
| | comund.line 

I | | strler? 

| | | aprintf? 

I | | atrlen? 

I | | atrcpy? 

I | | atrcat? 

I | announce 

I I I printf? 

I | usage 

1 | l printf? 

I | error.meaaage 

I I I printf? 

I I I fprintf? 

I | f ile.def aults 

I I I I0T? 

I | | atrckr? 

I | | atrcat? 

I I | atrtcpy? 

I | atrcmp? 

I | atrcpy? 

I I atrchr? 

I | fopen? 

I I FGETSIZE... 

I i fclose? 

I open, io .files 

( I file.open 

I | | I0T? 

I | | fopen? 

I I I atrcpy? 

I | | at meat? 

I | | atrcat? 

I | | strerror? 7 ~ 

I | | error_measage . . . 

I | fopen? 



PRECEDING PAGE BLANK NOT FILMED 
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I fclose? 

I strchr? 

| strcpy? 

| T9W0fl 

| rename? 
timestamp 

| strlen? 

| strnset? 

| time? 

| localtime? 

| st rat rim? 

| strcpy? 

| as c time? 

I right.fill 
| 1 strnMt? 

| | strlen? 

| fprintf? 

ConJoin.files 
| fgets... 

| strfnb? 

| fprintf? 

| strstr? 

| strcpy? 

| directive 
| | strcpy? 

| | strstr? 

| | strext 

I I I AID? 

| | 1 strstr? 

| | | strtcpy? 

I I I strcpy? 

J | | stratriM? 

| | strlsn? 

| I atoi? 

| | strnset? 

| | strfnb? 

| | strdup . . . 

| | strlwr? 

| | stratri*? 

| | strcap? 

j | «rror_Bessag«. . . 

| | sprintf? 

j | strinsart? 

| | AID? 

| | strcat? 

| access 
| | strext . . . 

| | ■atch.paraseters 

| | | I0T? 

j | | strstr? 

I } I strcpy? 

| | | error ,»essage, . . 

1 l | stratri*? 

| | | strtcpy? 

| | | strfnb? 
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I | strlen? 

I | AID? 

| | access. condition 

| | l stratrim? 

| | | strstr? 

I I I atoi? 

| | [ strlen? 

| | | strchr? 

I I I OR? 

| | | isdigit? 

| | | strdnp. . . 

{ | | strtrim. . . 

| | ! Btrfnb? 

| 10T? 

| open. access 

| | strcpy? 

| | I0T? 

| | fopen? 

| | street? 

j error .message . . . 

| printf? 

| fprintf? 

I scan.to.bgn.aatch 
| | fgetpos? 

| | f gets . . . 

| | strstr? 

| | fsetpos? 

I } error .message . . . 

1 copy.to.end.match 
I | fgetstr 

| | I IOT? 

I I I fgets... 

| | | isspace? 

| | | ORisprint? 

| | | street? 

| | | strtrim... 

I 1 IOT? 

I | strdnp . . . 

| | error .message . . . 

| | free? 

| | put line 

I I I HD? 

| | | strchr? 

I I I *in? 

I | 1 fprintf? 

| | strstr? 

I free? 

j fclose? 

strlen? 
fclose? 
free? 
printf? 
fopen? 
fprintf? 
access. lines? 
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C.2 Reference List 

The following list displays the invoked-by structure of functions within the 
Conjoin program. As in the previous section of this appendix, HIL appears 
at the whim of the reference-tree-producing tool. 

Conjoin.? iles : main 

FGETSIZE: initialization 

■IL: 

acc«t > : Conjoin.? lias 
access.condition: match.parameters 
announce: initialization 
command.! in* : initialization 

copy.to.end .match : access 

directive: Conjoin.? iles 

error_message : access copy.to.end. match directive 

?ila_open initialization match .parameters 

scan.to.bgn. match 

?gets: ConJoin.?iles ?getstr scan.to.bgn.match 

fgetstr: copy .to. end. match 
?ile .defaults: initialization 
?ile_open: open_io_?iles 
initialization: main 
main: 

match.parameters : access 
open.access : access 

open. io .files : main 

put line : copy _ to. end. mat ch 
right.fill : timestamp 
scan.to.bgn .match : access 

strdup: access. condition copy.to_end_match directive 


strext : access 


direct ive 


strtrim: 
timestamp : 


access. condition fgetstr 

main 


n*ag«: 


initialization 
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